astra-db-ts

@datastax/astra-db-ts is the officially maintained TypeScript/JavaScript client for DataStax Astra DB, the managed vector database built on Apache Cassandra. It wraps Astra’s Data API and DevOps API behind a strongly-typed, promise-based interface, letting Node.js applications create databases, manage keyspaces, and read/write data without hand-rolling HTTP calls or response parsing.

The client exposes two complementary data models under one root DataAPIClient: schemaless Collections for JSON documents (with $vector fields for similarity search) and strongly-typed Tables backed by CQL columns, where Table.schema() and InferTableSchema let TypeScript infer the row type directly from a column definition, similar in spirit to Zod or arktype but purpose-built for Astra’s wire format. A pluggable serialization layer (codecs) handles datatypes like vectors, big numbers, and UUIDs consistently across both models, and the options system (client → db → collection/table) deep-merges configuration so logging, timeouts, and serialization behavior can be set once and overridden locally.

What You Get

• A single DataAPIClient entrypoint that spawns Db and AstraAdmin instances, each inheriting a deep-merged options hierarchy for logging, timeouts, and serialization
• Two first-class data models — schemaless Collections for JSON documents with vector fields, and strongly-typed Tables where InferTableSchema derives the row type from a Table.schema() definition at compile time
• Built-in vector search via .sort({ vector }) cursors with .includeSimilarity(), plus standard filter/update/delete operations shared across both data models
• Admin operations (AstraAdmin, DbAdmin) for creating/listing databases and keyspaces, without leaving the same client hierarchy
• A pluggable HTTP transport (native fetch or fetch-h2 for HTTP/2) and an extensible codec registry for custom datatype (de)serialization
• Dual CJS/ESM builds with a generated public API report (etc/astra-db-ts.api.md) tracking the SDK’s exported surface across releases

Common Use Cases

• Building RAG (retrieval-augmented generation) pipelines that store document embeddings in Astra DB collections and query them via vector similarity search
• Migrating an existing CQL/Cassandra-shaped dataset to Astra DB using strongly-typed Tables with compile-time-inferred row types
• Provisioning and tearing down Astra databases/keyspaces programmatically as part of CI or multi-tenant application setup
• Running Astra DB from serverless or edge runtimes (Cloudflare Workers, Next.js) using the native-fetch transport without extra polyfills
• Connecting to non-Astra Data API backends (DSE, HCD) via UsernamePasswordTokenProvider for on-prem or self-managed Cassandra-with-Data-API deployments

Under The Hood

Architecture The DataAPIClient (src/client/data-api-client.ts) sits at the top of the hierarchy, extending a HierarchicalLogger base and spawning Db (src/db/db.ts) via .db() and AstraAdmin (src/administration/astra-admin.ts) via .admin(). Db in turn spawns Collection and Table instances plus DbAdmin variants (AstraDbAdmin, DataAPIDbAdmin) for keyspace/database management. Options for every layer flow through dedicated opts-handler classes (client/opts-handlers/{admin,db,root}-opts-handler.ts) that deep-merge parent and child configuration, matching the options-hierarchy diagram published in the project’s README. HTTP transport is abstracted behind a shared HttpClient with two concrete clients — one for the Data API, one for Astra’s DevOps/admin API — both built on a swappable Fetcher (native fetch or fetch-h2). A dedicated serialization layer (ser-des, codecs, ctx) maps documents and typed rows to and from the wire format for both Collections and Tables, and is the most architecturally distinctive part of the codebase. Changing the core Fetcher or ser-des contract would ripple through every command-issuing class, since Collection, Table, Db, and AstraAdmin all funnel through the same HTTP clients.

Tech Stack Written in strict-mode TypeScript (target es2020, module nodenext) for Node.js 18+, with a deliberately small runtime dependency set: bignumber.js for arbitrary-precision numerics, decoders for response validation, json-bigint and safe-stable-stringify for wire-format handling, and uuid for ID generation. There is no bundled web framework — this is a data client, not a server. It uses native fetch by default with an optional fetch-h2 integration for HTTP/2, supplied by the caller rather than dynamically imported. The build pipeline (a custom zx-based scripts/build.ts) produces dual CJS and ESM output with tsc-alias for path rewriting, and @microsoft/api-extractor generates a checked-in public API report, showing deliberate control over the SDK’s exported surface across releases.

Code Quality The test suite spans over 100 test files split cleanly into unit tests (mirroring the src/ layout: client, db, documents, administration, lib) and integration tests that exercise a live Data API instance across collections, tables, admin lifecycle, and quickstart scenarios. Mocha plus c8 coverage forms the core runner, supplemented by fast-check for property-based testing. Error handling is granular and typed rather than generic — every module (client, db, documents, administration, lib) defines its own error-class hierarchy, with the documents module alone containing an extensive dedicated errors file. TypeScript strict mode applies to both src and tests, and ESLint 9’s flat config with typescript-eslint enforces consistent style across the codebase.

What Makes It Unique The standout design choice is treating schemaless Collections and strongly-typed Tables as two first-class, parallel APIs under one client rather than bolting typed tables on as an afterthought — Table.schema() combined with InferTableSchema lets consumers derive a fully-typed row shape from a single schema definition, without a separate runtime validation dependency. The deep-merged options hierarchy (client → db → collection/table) avoids repetitive configuration for logging, timeouts, and serialization. A registrable codec system lets consumers customize how vectors, big numbers, and UUIDs serialize per collection or table, an extension point that goes beyond what most database clients expose. Documentation is unusually thorough for an SDK of this size, with runnable TSDoc examples embedded directly in class and method docstrings.