Releases: datastax/astra-db-ts
v2.0.1
Minor bug patch release
Minor patch to fix findAnd* commands not property deserializating the returned document
Note
See the https://github.com/datastax/astra-db-ts/releases/tag/v2.0.0 for the full release notes for the new 2.0.0 major version
v2.0.0
v2.0.0 - Major client overhaul
Warning
Release notes are still under construction
Table of contents
Note
Asterisks (*) by section names indicate those that include note of any breaking changes from v1.x to v2.x.
- What's new?
- Prerequisites*
- Data API tables support
findAndReranksupport- Overhaul of the logging system*
- Overhaul of the timeout system*
- Overhaul of cursors*
- Overhauls of certain admin functionality*
- Increased client compatibility across all environments*
- New fully-customizable ser/des system
- Errors improvements*
- Various minor changes and improvements
- Migration tips
What's new?
Prerequisites*
- Node.js v18 or higher
- TypeScript v5.0 or higher
Data API tables support
Adds complete support for Data API tables via the Table class.
Dual types*
Classes/types such as UpdateOneOptions, FindCursor, InsertManyError, etc. have been split into two different variants of each:
CollectionUpdateOneOptionsandTableUpdateOneOptions,CollectionFindandCursorTableFindCursor,CollectionInsertManyErrorandTableInsertManyError,- etc.
Collection methods on the Db class (such as db.collection(), db.createCollection(), db.listCollections(), etc.) now have sister methods for tables:
db.table(),db.createTable(),db.listTables(),- etc.
Indexes
Furthermore, tables necessitate indexes, which may be created through table.createIndex() (and its sister methods), and dropped through db.dropTableIndex().
Utility types
New utility types to infer the table's TS-type from its schema has been added as well:
InferTableSchemaInferTablePrimaryKey
Datatypes
Lastly, of the major additions, new datatypes have been added as well to support the new tables:
DataAPIBlobDataAPIDateDataAPITimeDataAPIDurationDataAPIInetDataAPIVectorBigNumber(re-exported frombignumber.js)
See DATATYPES.md for more information on the new datatypes.
findAndRerank support
Note
This is tied to the Overhaul of cursors section; please read that section as well for more information.
Preview hybrid search support has dropped via the collection.findAndRerank() method, which uses a new FindAndRerankCursor to iterate over its results.
New LexicalDoc type added as well as a sister type to VectorDoc and VectorizeDoc.
Overhaul of the logging system*
The logging system has evolved beyond a simple, immutable monitorCommands flag which would emit events only on the DataAPIClient class.
Now, logging is configured through the logging option anywhere along the options hierarchy, and adds a variety of new features:
- Events may log to the console as well now, as opposed to just being emitted as an event
- All classes in the client hierarchy are now event listeners
- These all extend the
HierarchicalLoggerclass, which implements a minimal event emitter - Events are bubbled up from the class they were emitted from, all the way up to the root
DataAPIClient - Event bubbling may be cancelled through
event.stop[Immediate]Propagation()like the DOM
- These all extend the
Logging may also be enabled/disabled/reconfigured on the fly, via the .updateLoggingConfig(<config>) method on any HierarchicalLogger instance (e.g. DataAPIClient, Db, Collection, etc.).
See the logging examples for more information.
Overhaul of the timeout system*
The timeout system has been overhauled to be more flexible and descriptive than the current singular maxTimeMS.
Timeouts are now configured through the timeoutDefaults parameter on class options interfaces, and the timeout parameter on method calls.
They are represented by the TimeoutDescriptor class, which contains the six following keys:
| Timeout Option | Description | Default |
|---|---|---|
requestTimeoutMs |
Maximum time the client waits for a response from the server | 15 seconds |
generalMethodTimeoutMs |
Timeout for general methods without a specific override (mostly doc/row-level ops) | 30 seconds |
collectionAdminTimeoutMs |
Timeout for collection admin operations (create, drop, list, etc.) | 1 minute |
tableAdminTimeoutMs |
Timeout for table admin operations (create, drop, list, alter, create/dropIndex, etc.) | 30 seconds |
databaseAdminTimeoutMs |
Timeout for database admin operations (create, drop, list, info, findEmbeddingProviders, etc.) | 10 minutes |
keyspaceAdminTimeoutMs |
Timeout for keyspace admin operations (create, drop, list) | 30 seconds |
In general, the requestTimeoutMs always corresponds to a single request from the server, but the rest of the timeouts account for the entire duration of the method, which is relevant in the case of multi-call methods.
A few important notes:
requestTimeoutMsapplies per individual HTTP request.- The other timeouts account for the entire duration of the method, which is relevant in the case of multi-call methods.
- Passing a
timeoutvalue as a plain number will use the most appropriate category for the method being called. - Setting a
timeoutto 0 disables it completely. - The legacy maxTimeMS option has been removed—simply replace it with
timeoutfor a quick migration path.
Overhaul of cursors*
v2.0.0-rc.1
v2.0.0-preview.5
v2.0.0-preview.4
v2.0.0-preview.3
v2.0.0-preview.2
- fix for process.env in the browser 7517a12
v2.0.0-preview.1
- remoaved feature-flag tables header 23245c2
- begrudgingly added InetAddress back as DataAPIInet 6aa0594
- DataAPIDuration massive overhaul 4ea6a97
- work for repl scirpt 98a9e66
- overhaul of times 9d087f2
- overhaul of dates ce54e01
- enhanced coll bignumbers support cbcc101
- reexport from version file 4b86423
- check for broken compilation when skipLibCheck: false w/ astra-db-ts as dep a8dfc4f
- bigints & counters now use bigint 29e5805
- killed DataAPITimestamp 344b10a
- proper checking for Bignumbers eea4db0
- separate scripts/check.sh file for typechecking/linting 3fc4f33
- UnexpectedDataAPIResponseError e1c342f
- ser-des work (#92) 60e616f
- Expand UUID versions (#91) 04af5e3
v2.0.0-preview.0
NOTE
The release notes are still under construction
The current commit list is just temporary
- slgihtly updated readme e86b308
- TSDoc + typing improvements + tweaks (#89) 0faa849
- Switch to codec-based ser/des system (#88) cfcf437
- Added complex r/w-aware
Table&Collectiontypes (#87) 95f8a41 - TSDoc progress + other minor fixes (#86) f31127b
- Various minor tweaks & cleanups for 2.0 (#84) 9a933f7
- Various 2.0 cleanups/tweaks (#83) 09d1d66
- Initial tables tests (#82) 9b26268
- Timeouts overhaul (#81) c8dc9fa
- Cursor split + tests (#80) 50361dd
- minor-ish tweaks/fixes 605d9ff
- Admin class overhauls (#79) 68873cb
- Rough, complete, roughly complete
Tableimplementation (#78) d0c6e0b - Initial logging implementation (#77) bee45ab
- Cursor refactors & alignment (#76) 4cca38f
- Initial tables implementation (#75) 432c807
- Deprecated features removal (#74) fc26224
- Major folder restructuring (#73) 263e90d
- updated eslint config 5dbedcd
v1.5.0
Namespace deprecation (docs link)
- The "namespace" terminology is now deprecated (still backwards compatible) everywhere
- There is a new "keyspace" alternative for each parameter name or method with "namespace" in it
- e.g.
db.useNamespace(...)still works, but now prefer thedb.useKeyspace(...)alternative
- All usages of "namespace" will be removed in an upcoming major release
Other deprecations (to be removed in v2.0)
collection.bulkWrite()is now deprecated- Prefer to just manually call the functions yourself
db.collections()is also now deprecated- Equivalent to
(await db.listCollections()).map(c => new Collection(c.name))
- Equivalent to
Misc improvements/fixes
collection.drop()will now work properly if the collection is in a non-default keyspace- Before, it would attempt to drop the collection from
'default_keyspace'
- Before, it would attempt to drop the collection from
returnDocumentonfindOneAnd*functions are finally optional- Defaults to
'before'on the Data API
- Defaults to
updateDbNamespacewas changed to immediately set the new keyspace- Before, it would wait for the keyspace to be created first
- This would lead to easier race conditions, and they keyspace wouldn't be set at all if creation errored
- Before, it would wait for the keyspace to be created first
[Admin]CommandSucceededEventsnow have awarningsfield for any warnings the Data API may return- These may point out deprecated/incorrect practices, or any other issues that aren't strictly an error.
- (e.g. using the now-deprecated
(create|find|drop)Namespaceadmin commands on DSE/HCD)
- Added missing DB statuses to the
DatabaseStatusenum (e.g.'HIBERNATED'and'HIBERNATING')- You can check the diff here
- Better error for if the
Adminclasses don't have a token set- (for the astra variants)
- Various error message improvements throughout the client
- Fixed some errors being obfuscated, improved the clarity of a few, added
' (+ more <num_errors> errors)'to the end of aggregated errors
- Fixed some errors being obfuscated, improved the clarity of a few, added
- Exposed
FetchH2andFetchNativefetchers to make it easier to wrap them with your own for customization purposes- For use with setting a
'custom'client
- For use with setting a
- Exposed
DEFAULT_KEYSPACEconstant
Internal stuff
(Too many changes to list in detail, but here are the highlights)
- MAJOR overhaul of test suite
- Massively parallelized tests (full test suite used to take over 50 min to run.. now it barely takes 10 minutes!)
- Majorly improved test filtering through custom filtering functionality
- Custom test report file generated to store full errors thrown during tests
- Test suite sets up and cleans up after itself much better now (tests much more reproducible now)
- Custom test script CLI to make running tests super easy
- Vectorize tests wait for providers to warm up now instead of erroring out after the first try
- Much more info here
- Updated ESLint + config
- Including adding rules to add all missing semicolons/commas
shell.nix+nix-direnv- Setups up shell env w/
nodejs_20,jq, and theastraCLI - Also adds the
scriptsdir toPATH
- Setups up shell env w/
repl.shscript- Much easier way to quickly test out
astra-db-tsfunctionality - Added
-lightoption to build script to set up REPL quicker- Doesn't typecheck or do any extraneous code transformations (such as stripping comments)
- Much easier way to quickly test out
returnDocumentResponsesimplementation- Fully implemented, but not used until Data API issue is resolved