diff --git a/README.md b/README.md index 26d96e27..8db967e2 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,16 @@ > **Warning** > This README is still under construction; parts of it may be incomplete or outdated. -*This README targets v2.0.0+, which introduces a whole new API. Click [here](https://github.com/datastax/astra-db-ts/tree/v1.x?tab=readme-ov-file#datastaxastra-db-ts) for the pre-existing client readme.* +*This README targets v2.0.0+, which expands on the previous 1.x API. Click [here](https://github.com/datastax/astra-db-ts/tree/v1.x?tab=readme-ov-file#datastaxastra-db-ts) for the pre-existing client readme.* ## Table of contents - [Quickstart](#quickstart) - [Collections](#collections) - [Tables](#tables) - [High-level architecture](#high-level-architecture) -- [Getting the most out of the typing](#getting-the-most-out-of-the-typing) -- [Working with Dates](#working-with-dates) -- [Working with ObjectIds and UUIDs](#working-with-objectids-and-uuids) -- [Monitoring/logging](#monitoringlogging) -- [Non-astra support](#non-astra-support) + - [Options hierarchy](#options-hierarchy) +- [Datatypes](#datatypes) +[Non-astra support](#non-astra-support) - [Non-standard environment support](#non-standard-environment-support) - [HTTP/2 with minification](#http2-with-minification) - [Browser support](#browser-support) @@ -70,9 +68,9 @@ interface Dream extends VectorDoc { // Let's see what we've got const cursor = collection.find({}) - .sort({ vector: vector([0, 0.2, 0.4]) }) // Performing a vector search - .includeSimilarity(true) // The found doc is inferred to have `$similarity` as a property now - .limit(2); + .sort({ vector: vector([0, 0.2, 0.4]) }) // Performing a vector search + .includeSimilarity(true) // The found doc is inferred to have `$similarity` as a property now + .limit(2); // This would print: // - Surfers' paradise: 0.98238194 @@ -113,11 +111,11 @@ const mkDreamsTable = async () => await db.createTable('dreams', { // Infer the TS-equivalent type from the table definition (like zod or arktype). Equivalent to: // -// interface TableSchema extends Row<'id'> { -// id: number, -- A primary key component, so it's required -// summary?: string | null, -- Not a primary key, so it's optional and may return as null when found -// tags?: Set, -- Sets/maps/lists are optional to insert, but will actually be returned as empty collections instead of null -// vector?: DataAPIVector | null, -- Vectors, however, may be null. +// interface TableSchema { +// id: number, -- A primary key component, so it's required +// summary?: string | null, -- Not a primary key, so it's optional and may return as null when found +// tags?: Set, -- Sets/maps/lists are optional to insert, but will actually be returned as empty collections instead of null +// vector?: DataAPIVector | null, -- Vectors, however, may be null. // } type Dream = InferTableSchema; @@ -181,7 +179,23 @@ type Dream = InferTableSchema; `astra-db-ts`'s abstractions for working at the data and admin layers are structured as depicted by this diagram: -![Class hierarchy diagram](etc/imgs/class-hierarchy.png) +```mermaid +flowchart TD + DataAPIClient -->|".db(endpoint)"| Db + DataAPIClient -->|".admin()"| AstraAdmin + + Db --->|".collection(name) + .createCollection(name)"| Collection + + Db --->|".table(name) + .createTable(name)"| Table + + AstraAdmin -->|".dbAdmin(endpoint) + .dbAdmin(id, region)"| DbAdmin + + Db -->|".admin()"| DbAdmin + DbAdmin -->|".db()"| Db +``` Here's a small admin-oriented example: @@ -204,139 +218,23 @@ const admin = client.admin(); })(); ``` -## Getting the most out of the typing - -`astra-db-ts` is a typescript-first library, performing minimal runtime type-checking. As such, it provides -a rich set of types to help you write type-safe code. - -Here are some examples of how you can properly leverage types to make your code more robust: - -```typescript -// First of all: -// I *highly* recommend writing your query objects & filter objects and such inline with the methods -// to get the best possible type-checking and autocomplete - -import { DataAPIClient, StrictFilter, StrictSort, UUID } from '@datastax/astra-db-ts'; - -const client = new DataAPIClient('*TOKEN*'); -const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' }); - -// You can strictly type your collections for proper type-checking -interface Person { - _id: UUID, - name: string, - interests: { - favoriteBand?: string, - friend?: UUID, - } -} - -(async () => { - // Create your collections with a defaultId type to enforce the type of the _id field - // (Otherwise it'll default to a string UUID that wouldn't be deserialized as a UUID by the client) - const collection = await db.createCollection('my_collection', { defaultId: { type: 'uuidv7' } }); - - // Now it'll raise type-errors if you try to insert a document with the wrong shape - await collection.insertOne({ - _id: new UUID('e7f1f3a0-7e3d-11eb-9439-0242ac130002'), - name: 'John', - interests: { - favoriteBand: 'Nightwish', - }, - // @ts-expect-error - 'eyeColor' does not exist in type MaybeId - eyeColor: 'blue', - }); -})(); -``` - -## Working with Dates - -Native JS `Date` objects can be used anywhere in documents to represent dates and times. +### Options hierarchy -Document fields stored using the `{ $date: number }` will also be returned as Date objects when read. +Like the client hierarchy, the options for each class also exist in a hierarchy. -```typescript -import { DataAPIClient } from '@datastax/astra-db-ts'; - -// Reference an untyped collections -const client = new DataAPIClient('*TOKEN*'); -const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' }); +The general options for parent classes are deeply merged with the options for child classes. -(async () => { - const collection = await db.createCollection('dates_test'); - - // Insert documents with some dates - await collection.insertOne({ dateOfBirth: new Date(1394104654000) }); - await collection.insertOne({ dateOfBirth: new Date('1863-05-28') }); - - // Update a document with a date and setting lastModified to now - await collection.updateOne( - { - dateOfBirth: new Date('1863-05-28'), - }, - { - $set: { message: 'Happy Birthday!' }, - $currentDate: { lastModified: true }, - }, - ); - - // Will print *around* `new Date()` (i.e. when server processed the request) - const found = await collection.findOne({ dateOfBirth: { $lt: new Date('1900-01-01') } }); - console.log(found?.lastModified); - - // Cleanup (if desired) - await collection.drop(); -})(); +```mermaid +graph TD + DataAPIClientOptions --> AdminOptions + DataAPIClientOptions --> DbOptions + DbOptions --> CollectionOptions + DbOptions --> TableOptions ``` -## Working with ObjectIds and UUIDs - -`astra-db-ts` exports an `ObjectId` and `UUID` class for working with these types in the database. - -Note that these are custom classes, and *not* the ones from the `bson` package. Make sure you're using the right one! +## Datatypes -```typescript -import { DataAPIClient, ObjectId, UUID } from '@datastax/astra-db-ts'; - -interface Person { - _id: ObjectId | UUID, - name: string, - friendId?: ObjectId | UUID, -} - -// Connect to the db -const client = new DataAPIClient('*TOKEN*'); -const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' }); - -(async () => { - // Create a collections with a UUIDv7 as the default ID - const collection = await db.createCollection('ids_test', { defaultId: { type: 'uuidv7' } }); - - // You can manually set whatever ID you want - await collection.insertOne({ _id: new ObjectId("65fd9b52d7fabba03349d013"), name: 'John' }); - - // Or use the default ID - await collection.insertOne({ name: 'Jane' }); - - // Let's give Jane a friend with a UUIDv4 - const friendId = UUID.v4(); - - await collection.insertOne({ name: 'Alice', _id: friendId }); - - await collection.updateOne( - { name: 'Jane' }, - { $set: { friendId } }, - ); - - // And let's get Jane as a document - // (Prints "Jane", the generated UUIDv4, and true) - const jane = await collection.findOne({ name: 'Jane' }); - console.log(jane?.name, jane?.friendId?.toString(), friendId.equals(jane?.friendId)); - - // Cleanup (if desired) - await collection.drop(); -})(); -``` +See [DATATYPES.md](etc/docs/DATATYPES.md) for a full list of supported datatypes and their TypeScript equivalents. ## Non-astra support @@ -354,8 +252,9 @@ const db = client.db('*ENDPOINT*'); // You'll also need to pass it to db.admin() when not using Astra for typing purposes // If the environment does not match, an error will be thrown as a reminder -const dbAdmin: DataAPIDbAdmin = db.admin({ environment: 'dse' }); -dbAdmin.createNamespace(...); +// `environment: 'dse'` makes the return type be `DataAPIDbAdmin` +const dbAdmin = db.admin({ environment: 'dse' }); +dbAdmin.createNamespace('...'); ``` The `TokenProvider` class is an extensible concept to allow you to create or even refresh your tokens diff --git a/etc/astra-db-ts.api.md b/etc/astra-db-ts.api.md index 63eb9ee2..c112fd9c 100644 --- a/etc/astra-db-ts.api.md +++ b/etc/astra-db-ts.api.md @@ -138,7 +138,7 @@ export class AstraAdmin { dbAdmin(endpoint: string, options?: DbOptions): AstraDbAdmin; dbAdmin(id: string, region: string, options?: DbOptions): AstraDbAdmin; dbInfo(id: string, options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise; - dropDatabase(db: Db | string, options?: DropAstraDatabaseOptions): Promise; + dropDatabase(db: Db | string, options?: AstraDropDatabaseOptions): Promise; // Warning: (ae-forgotten-export) The symbol "DevOpsAPIHttpClient" needs to be exported by the entry point index.d.ts // // (undocumented) @@ -214,7 +214,10 @@ export type AstraDbStatus = 'ACTIVE' | 'ERROR' | 'DECOMMISSIONING' | 'DEGRADED' // @public export type AstraDbStatusFilter = AstraDbStatus | 'ALL' | 'NONTERMINATED'; -// @public (undocumented) +// @public +export type AstraDropDatabaseOptions = AstraAdminBlockingOptions & WithTimeout<'databaseAdminTimeoutMs'>; + +// @public export type AstraDropKeyspaceOptions = AstraAdminBlockingOptions & WithTimeout<'keyspaceAdminTimeoutMs'>; // @public @@ -729,7 +732,7 @@ export interface CreateCollectionOptions extends Collect timeout?: number | Pick, 'collectionAdminTimeoutMs'>; } -// @public (undocumented) +// @public export type CreateTableColumnDefinitions = Record; // @public @@ -752,8 +755,8 @@ export interface CreateTableOptions { @@ -939,7 +942,7 @@ export type DataAPILoggingConfig = DataAPILoggingEvent | readonly (DataAPILoggin // Warning: (ae-incompatible-release-tags) The symbol "DataAPILoggingDefaults" is marked as @public, but its signature references "NormalizedLoggingConfig" which is marked as @internal // -// @public (undocumented) +// @public export const DataAPILoggingDefaults: NormalizedLoggingConfig[]; // @public @@ -1161,9 +1164,6 @@ export class DevOpsUnexpectedStateError extends DevOpsAPIError { readonly expected: string[]; } -// @public -export type DropAstraDatabaseOptions = AstraAdminBlockingOptions & WithTimeout<'databaseAdminTimeoutMs'>; - // @public export interface DropCollectionOptions extends WithTimeout<'collectionAdminTimeoutMs'>, WithKeyspace { } @@ -1351,7 +1351,7 @@ export type FoundRow = { [K in keyof Doc]-?: DataAPIVector extends Doc[K] ? Exclude : Doc[K]; }; -// @public (undocumented) +// @public export interface FullCreateTablePrimaryKeyDefinition { // (undocumented) readonly partitionBy: readonly string[]; @@ -1562,7 +1562,7 @@ export interface ListCollectionsOptions extends WithTimeout<'collectionAdminTime nameOnly?: boolean; } -// @public (undocumented) +// @public export interface ListCreateTableColumnDefinition { // (undocumented) type: 'list'; @@ -1570,10 +1570,10 @@ export interface ListCreateTableColumnDefinition { valueType: TableScalarType; } -// @public (undocumented) +// @public export type ListTableColumnDefinitions = Record; -// @public (undocumented) +// @public export interface ListTableDefinition { // (undocumented) columns: ListTableColumnDefinitions; @@ -1581,10 +1581,12 @@ export interface ListTableDefinition { primaryKey: ListTablePrimaryKeyDefinition; } -// @public (undocumented) -export type ListTableKnownColumnDefinition = StrictCreateTableColumnDefinition; +// @public +export type ListTableKnownColumnDefinition = StrictCreateTableColumnDefinition & { + apiSupport?: ListTableUnsupportedColumnApiSupport; +}; -// @public (undocumented) +// @public export type ListTablePrimaryKeyDefinition = Required; // @public @@ -1592,19 +1594,21 @@ export interface ListTablesOptions extends WithTimeout<'tableAdminTimeoutMs'>, W nameOnly?: boolean; } -// @public (undocumented) +// @public export interface ListTableUnsupportedColumnApiSupport { // (undocumented) cqlDefinition: string; // (undocumented) createTable: boolean; // (undocumented) + filter: boolean; + // (undocumented) insert: boolean; // (undocumented) read: boolean; } -// @public (undocumented) +// @public export interface ListTableUnsupportedColumnDefinition { // (undocumented) apiSupport: ListTableUnsupportedColumnApiSupport; @@ -1612,13 +1616,13 @@ export interface ListTableUnsupportedColumnDefinition { type: 'UNSUPPORTED'; } -// @public (undocumented) +// @public export type LooseCreateTableColumnDefinition = TableScalarType | string; -// @public (undocumented) +// @public export interface MapCreateTableColumnDefinition { // (undocumented) - keyType: TableScalarType; + keyType: 'text' | 'ascii'; // (undocumented) type: 'map'; // (undocumented) @@ -1729,7 +1733,7 @@ export interface RunCommandOptions extends WithTimeout<'generalMethodTimeoutMs'> table?: string; } -// @public (undocumented) +// @public export interface ScalarCreateTableColumnDefinition { // (undocumented) type: TableScalarType; @@ -1738,7 +1742,7 @@ export interface ScalarCreateTableColumnDefinition { // @public (undocumented) export type SerDesFn = (key: string, value: any, ctx: Ctx) => readonly [0 | 1 | 2, any?, string?] | 'Return ctx.done(val?), ctx.recurse(val?), ctx.continue(), or void'; -// @public (undocumented) +// @public export interface SetCreateTableColumnDefinition { // (undocumented) type: 'set'; @@ -1746,9 +1750,6 @@ export interface SetCreateTableColumnDefinition { valueType: TableScalarType; } -// @public (undocumented) -export type ShortCreateTablePrimaryKeyDefinition = string; - // @public (undocumented) export type SomeCodec = NameCodec | PathCodec | TypeCodec | CustomGuardCodec | ClassGuardCodec; @@ -1773,7 +1774,7 @@ export class StaticTokenProvider extends TokenProvider { getToken(): string; } -// @public (undocumented) +// @public export type StrictCreateTableColumnDefinition = ScalarCreateTableColumnDefinition | MapCreateTableColumnDefinition | ListCreateTableColumnDefinition | SetCreateTableColumnDefinition | VectorCreateTableColumnDefinition; // @public @@ -1955,7 +1956,7 @@ export interface TableOptions extends WithKeyspace { timeoutDefaults?: Partial; } -// @public (undocumented) +// @public export type TableScalarType = 'ascii' | 'bigint' | 'blob' | 'boolean' | 'date' | 'decimal' | 'double' | 'duration' | 'float' | 'int' | 'inet' | 'smallint' | 'text' | 'time' | 'timestamp' | 'tinyint' | 'uuid' | 'varint'; // @public (undocumented) @@ -2077,10 +2078,10 @@ export const uuid: (uuid: string | 1 | 4 | 6 | 7) => UUID; // @public export const vector: (v: DataAPIVectorLike) => DataAPIVector; -// @public (undocumented) +// @public export interface VectorCreateTableColumnDefinition { // (undocumented) - dimension?: number; + dimension: number; // (undocumented) service?: VectorizeServiceOptions; // (undocumented) diff --git a/etc/docs/DATATYPES.md b/etc/docs/DATATYPES.md new file mode 100644 index 00000000..b74d2f3c --- /dev/null +++ b/etc/docs/DATATYPES.md @@ -0,0 +1,526 @@ +# Datatypes + +`astra-db-ts` exports a variety of custom datatype classes to represent their respective types in the database. + +Some types are strictly meant for tables; others for collections. And a couple, i.e. `UUID` and `DataAPIVector`, are used in both. + +### Table of Contents + +- [Collections](#collections) + - [Overview](#overview) + - [BigNumbers](#bignumbers) + - [Dates](#dates) + - [ObjectIds](#objectids) + - [UUIDs](#uuids) + - [Vectors](#vectors) +- [Tables](#tables) + - [Overview](#overview-1) + - [BigNumbers](#bignumbers-1) + - [Blobs](#blobs) + - [Collections](#collections-1) + - [Dates/Times](#dates--times) + - [InetAddresses](#inetaddresses) + - [UUIDs](#uuids-1) + - [Vectors](#vectors-1) +- [Inserting native representations](#inserting-native-representations) +- [Cheatsheet](#cheatsheet) + - [Collections](#collections-2) + - [Tables](#tables-1) + +## Collections + +### Overview + +Types in collections are natively represented through the `{ $type: '' }` syntax, e.g. + +```typescript +await collection.insertOne({ + date: { $date: 1734070574056 }, + uuid: { $uuid: 'f47ac10b-58cc-4372-a567-0e02b2c3d479' }, + oid: { $objectId: '507f1f77bcf86cd799439011' }, + $vector: [.1, .2, .3], +}); +``` + +However, `astra-db-ts` provides utility types to make working with these values easier. + +The idiomatic equivalent to the above would be: + +```typescript +import { DataAPIVector, ObjectId, UUID } from '@datastax/astra-db-ts'; + +await collection.insertOne({ + date: new Date(), + uuid: UUID.v4(), + oid: new ObjectId(), + $vector: new DataAPIVector([.1, .2, .3]), +}); +``` + +Or, if you prefer to use the available shorthand functions: + +```typescript +import { oid, uuid, vector } from '@datastax/astra-db-ts'; + +await collection.insertOne({ + date: new Date(), + uuid: uuid(4), + oid: oid(), + $vector: vector([.1, .2, .3]), +}); +``` + +### BigNumbers + +> **NOTE** +> Enabling BigNumbers support for a collection will force a slower, bignum-friendly JSON library to be used for all documents in that collection. The difference should be negligible for most use-cases. + +Proper big-number support is still under works in `astra-db-ts`, but a rough version is out currently. + +You **must** set `serdes.enableBigNumbers: true` somewhere along the options hierarchy for collections to be able to work with `bigint`s & `BigNumber`s. + +Under the current rough support, you may pass any of `number`, `bigint`, or `BigNumber` to the database (in any field), and it'll be stored as a `decimal` in the database. + +When reading back, the `decimal` will be returned as a `number` if it's within the safe `number` range, and as a `string` otherwise; currently, it's on the user to handle the conversion to `bigint` or `BigNumber` as desired. + +Note that this is the same `BigNumber` from `bignumber.js`, just reexported from `@datastax/astra-db-ts`. + +```typescript +import { BigNumber } from '@datastax/astra-db-ts'; + +const collection = db.collection('my_coll', { + serdes: { enableBigNumbers: true }, +}); + +await collection.insertOne({ + bigint1: 1234567890123456789012345672321312312890n, + bigint2: 10n, + decmial: new BigNumber('12345678901234567890123456.72321312312890'), +}); + +const doc = await collection.findOne(); + +console.log(doc.bigint1.toString()); // Will be returned as a `string` +console.log(doc.bigint2.toString()); // Will just be a normal `number` as it's within the safe `number` range +console.log(doc.decimal.toString()); // Will be returned as a `string` +``` +When reading back, the `decimal` will be returned as a `number` if it's within the safe `number` range, and as a `string` otherwise; currently, it's on the user to handle the conversion to `bigint` or `BigNumber` as desired. + +Note that this is the same `BigNumber` from `bignumber.js`, just reexported from `@datastax/astra-db-ts`. + +```typescript +import { BigNumber } from '@datastax/astra-db-ts'; + +const collection = db.collection('my_coll', { + serdes: { enableBigNumbers: true }, +}); + +await collection.insertOne({ + bigint1: 1234567890123456789012345672321312312890n, + bigint2: 10n, + decmial: new BigNumber('12345678901234567890123456.72321312312890'), +}); + +const doc = await collection.findOne(); +console.log(doc.bigint1.toString()); // Will be returned as a `string` +console.log(doc.bigint2.toString()); // Will just be a normal `number` as it's within the safe `number` range +console.log(doc.decimal.toString()); // Will be returned as a `string` +``` + +### Dates + +Dates in collections are represented as just normal, native JS `Date` objects. + +```typescript +await collection.insertOne({ + date: new Date(), +}); + +const doc = await collection.findOne(); +console.log(doc.date instanceof Date); // true +``` + +If you prefer to use `DataAPITimestamp`s for interop with tables, that's also allowed, though you'll need to enable a certain codec if you want to read the date back as a `DataAPITimestamp`. + +- `DataAPITimestamp`s will still serialize to a `$date` by default, even if you don't set the necessary codec. + +```typescript +import { CollCodecs, DataAPITimestamp, timestamp } from '@datastax/astra-db-ts'; + +const collection = db.collection('my_coll', { + serdes: { codecs: [CollCodecs.USE_DATA_API_TIMESTAMPS_FOR_DATES] }, +}); + +await collection.insertOne({ + date: timestamp(), // Equivalent to `new DataAPITimestamp()` +}); + +const doc = await collection.findOne(); +console.log(doc.date instanceof DataAPITimestamp); // true +``` + +### ObjectIds + +You can use objectIds in collections using the `ObjectId` class (or the `oid` shorthand). Make sure you're importing this from `'@datastax/astra-db-ts'`, and _not_ from `'bson'`. + +```typescript +import { ObjectId, oid } from '@datastax/astra-db-ts'; + +await collection.insertOne({ + _id: oid(), // Equivalent to `new ObjectId()` +}); + +const doc = await collection.findOne(); +console.log(doc._id instanceof ObjectId); // true +``` + +You can create an `ObjectId` through the constructor function, or through the `oid` shorthand, in three different ways: +1. Provide the objectId as a string (`'507f1f77bcf86cd799439011'`) +2. Provide the timestamp you want the objectID to be based on (`1734070574056`) +3. Leave it `undefined`/`null` to generate a new `ObjectID` based on the current timestamp + +From the `ObjectId` class, you can either: +- Get the timestamp as a `Date` using `.getTimestamp()` +- Get the string representation of the `ObjectId` using `.toString()` +- Compare it with another `ObjectId` or `string` using `.equals()` + +### UUIDs + +You can use UUIDs in collections using the `UUID` class (or the `uuid` shorthand). Make sure you're importing this from `'@datastax/astra-db-ts'`, and _not_ from `'uuid'` or `'bson'`. + +```typescript +import { UUID, uuid } from '@datastax/astra-db-ts'; + +await collection.insertOne({ + _id: uuid(4), // Equivalent to `UUID.v4()` +}); + +const doc = await collection.findOne(); +console.log(doc._id instanceof UUID); // true +``` + +You can create a `UUID` through the class, or through the `uuid` shorthand, in a few different ways: +1. By passing the UUID string to `new UUID()` or `uuid()` +2. By using `UUID.v1()`, `.v4()`, `.v6()`, or `.v7()` to generate a new UUID of the respective version +3. By using `uuid(1)`, `uuid(4)`, `uuid(6)`, or `uuid(7)` to generate a new UUID of the respective version + +From the `UUID` class, you can either: +- Get the string representation of the `UUID` using `.toString()` +- Compare it with another `UUID` or `string` using `.equals()` +- Get the version of the `UUID` using `.version` +- Get the timestamp of a `v1` or `v7` `UUID` using `.getTimestamp()` + - Note that this is [generally not recommended](https://www.rfc-editor.org/rfc/rfc9562.html#section-6.12), but it's there if you really need it + +### Vectors + +`$vector`/`$vectorize` are a special case where they're not types, but rather a special reserved name for working with an embedding vector. + +```typescript +import { vector } from '@datastax/astra-db-ts'; + +await collection.insertOne({ + $vector: vector([.1, .2, .3]), // Equivalent to `new DataAPIVector([.1, .2, .3])` +}); +``` + +Using `DataAPIVector` for insertion isn't strictly necessary; neither `astra-db-ts`, nor the server, will complain if the vector is inserted in any of the following ways: +- `$vector: [.1, .2, .3]` +- `$vector: { $binary: '' }` +- `$vector: new DataAPIVector([.1, .2, .3])` +- `$vector: vector([.1, .2, .3])` + +However, keep in mind that when `find`-ing, the `$vector` will _always_ be returned as a `DataAPIVector`, to smooth the difference between the underlying representations. + +```typescript +const doc = await collection.findOne(); +console.log(doc.$vector instanceof DataAPIVector); // true +``` + +You can create a `DataAPIVector` through the constructor function, or through the `vector` shorthand, by providing the vector in four different ways: +1. As an array of numbers (`[.1, .2, .3]`) +2. In its "binary" representation (`{ $binary: '' }`) +3. As a `Float32Array` (`new Float32Array([.1, .2, .3])`) +4. As a `DataAPIVector`, which copies its internal state into a new `DataAPIVector` + +From the `DataAPIVector` class, you can either: +- Get the length of the vector (in O(1) time) using `.length` +- Get the "raw" underlying vector using `.raw()` +- Get the vector in your desired format (converting if necessary) using one of: + - `.asArray()` + - `.asFloat32Array()` + - `.asBase64()` + +## Tables + +### Overview + +Tables have a known type on the server, but the client doesn't have a way to know what that schema is, so it's up to the user to provide the correct types using their respective `astra-db-ts`-provided types as necessary. + +Collection types (maps/sets/lists) are represented by their native JavaScript counterparts, e.g. + +A variety of scalar types, however, are represented by custom `astra-db-ts`-provided classes. + +### BigNumbers + +> **NOTE** +> Enabling BigNumbers support for a collection will force a slower, bignum-friendly JSON library to be used for all documents in that collection. The difference should be negligible for most use-cases. + +Unlike collections, `bigint`s & `BigNumber`s are supported completely and natively in tables; you don't need to enable any special options to use them. + +The performance penalty still applies, however, but it's only in play when there's actually a `bigint` or `BigNumber` present in the object. + +While you may technically pass any of `number`, `bigint`, or `BigNumber` to the database, it'll be read back as: +- a `bigint` if the column is a `varint` +- a `BigNumber` if the column is a `decimal` + +```typescript +import { BigNumber } from '@datastax/astra-db-ts'; + +await table.insertOne({ + bigint1: 1234567890123456789012345672321312312890n, + bigint2: 10n, + decmial: new BigNumber('12345678901234567890123456.72321312312890'), +}); + +const row = await table.findOne(); +console.log(row.bigint1.toString()); // Will be returned as a `bigint` +console.log(row.bigint2.toString()); // Will be returned as a `bigint` +console.log(row.decimal.toString()); // Will be returned as a `BigNumber` +``` + +### Blobs + +You can use blobs in tables using the `DataAPIBlob` class (or the `blob` shorthand). + +```typescript +import { blob, DataAPIBlob } from '@datastax/astra-db-ts'; + +await table.insertOne({ + blob: blob(Buffer.from([0x0, 0x1, 0x2])), // Equivalent to `new DataAPIBlob(...)` +}); + +const row = await collection.findOne(); +console.log(row.blob instanceof DataAPIBlob); // true +``` + +You can create a `DataAPIBlob` through the constructor function, or through the `blob` shorthand, by providing the binary data in four different ways: +1. As a Node.js Buffer, if available (`Buffer.from([0x0, 0x1, 0x2])`) +2. As a more generic ArrayBuffer (`new ArrayBuffer(...)`) +3. In its "binary" representation (`{ $binary: '' }`) +4. As a `DataAPIBlob`, which copies its internal state into a new `DataAPIBlob` + +From the `DataAPIBlob` class, you can either: +- Get the byte-length of the blob (in O(1) time) using `.byteLength` +- Get the "raw" underlying binary data using `.raw()` +- Get the blob in your desired format (converting if necessary) using one of: + - `.asBuffer()` + - `.asArrayBuffer()` + - `.asBase64()` + +### Collections + +The `map`, `set`, and `list` types are represented by their native JavaScript counterparts (`Map`/`Set`/`Array`), and accept nested (scalar) datatypes. + +```typescript +await table.insertOne({ + map: new Map([['key', 'value']]), + set: new Set(['value']), + list: ['value'], +}); + +const row = await table.findOne(); +console.log(row.map.get('key')); // 'value' +console.log(row.set.has('value')); // true +console.log(row.list[0]); // 'value' +``` + +### Dates & times + +Due to the variety of date & time classes available through the Data API, four custom classes are provided to represent them in the client. + +```typescript +import { date, duration, time, timestamp, ... } from '@datastax/astra-db-ts'; + +await table.insertOne({ + date: date(), // Equivalent to `new DataAPIDate()` + time: time(), // Equivalent to `new DataAPITime()` + timestamp: timestamp(), // Equivalent to `new DataAPITimestamp()` + duration: duration('P5DT30M'), // Equivalent to `new DataAPIDuration(...)` +}); + +const row = await table.findOne(); +console.log(row.date instanceof DataAPIDate); // true +console.log(row.time instanceof DataAPITime); // true +console.log(row.timestamp instanceof DataAPITimestamp); // true +console.log(row.duration instanceof DataAPIDuration); // true +``` + +You can create these classes through the constructor function, or through the respective shorthand, by providing the date/time/duration in a few different ways: +1. As a raw string formatted as it would be stored in the database (`'1992-05-28'`, `'12:34:56'`, `'2021-09-30T12:34:56.789Z'`, `'P5DT30M'`) +2. As a `Date` object (`new Date(1734070574056)`) + - Durations are the exception here, as they doesn't have a direct `Date` equivalent +3. As the `*Components` object for that respective class (e.g. `{ year: 1992, month: 5, day: 28 }`) + +From each class, you can generally: +- Get the string representation of the date/time/duration using `.toString()` +- Get the date/time as a `Date` object using `.toDate()` +- Get the individual components of the date/time using `.components()` + +### InetAddresses + +You can use inets in collections using the `InetAddress` class (or the `inet` shorthand). + +```typescript +import { InetAddress, inet } from '@datastax/astra-db-ts'; + +await table.insertOne({ + inet: inet('::1'), // Equivalent to `new InetAddress('::1')` +}); + +const row = await table.findOne(); +console.log(row.inet instanceof InetAddress); // true +``` + +You can create a `InetAddress` through the class, or through the `inet` shorthand, in a few different ways: +1. By passing the inet string to `new InetAddress()` or `inet()`, and having the version be inferred +2. By passing the inet string to `new InetAddress()` or `inet()`, and specifying the version explicitly (validating as that version) + - e.g. `inet('::1', 6)` + +From the `InetAddress` class, you can either: +- Get the string representation of the `InetAddress` using `.toString()` +- Get the version of the `InetAddress` using `.version` + +### UUIDs + +You can use UUIDs in collections using the `UUID` class (or the `uuid` shorthand). Make sure you're importing this from `'@datastax/astra-db-ts'`, and _not_ from `'uuid'` or `'bson'`. + +```typescript +import { UUID, uuid } from '@datastax/astra-db-ts'; + +await table.insertOne({ + uuid: uuid(4), // Equivalent to `UUID.v4()` +}); + +const row = await table.findOne(); +console.log(row.uuid instanceof UUID); // true +``` + +You can create a `UUID` through the class, or through the `uuid` shorthand, in a few different ways: +1. By passing the UUID string to `new UUID()` or `uuid()` +2. By using `UUID.v1()`, `.v4()`, `.v6()`, or `.v7()` to generate a new UUID of the respective version +3. By using `uuid(1)`, `uuid(4)`, `uuid(6)`, or `uuid(7)` to generate a new UUID of the respective version + +From the `UUID` class, you can either: +- Get the string representation of the `UUID` using `.toString()` +- Compare it with another `UUID` or `string` using `.equals()` +- Get the version of the `UUID` using `.version` +- Get the timestamp of a `v1` or `v7` `UUID` using `.getTimestamp()` + - Note that this is [generally not recommended](https://www.rfc-editor.org/rfc/rfc9562.html#section-6.12), but it's there if you really need it + +### Vectors + +You can use vectors in tables using the `DataAPIVector` class (or the `vector` shorthand). + +```typescript +import { vector } from '@datastax/astra-db-ts'; + +await table.insertOne({ + vector: vector([.1, .2, .3]), // Equivalent to `new DataAPIVector([.1, .2, .3])` +}); +``` + +Using `DataAPIVector` for insertion isn't strictly necessary; neither `astra-db-ts`, nor the server, will complain if the vector is inserted in any of the following ways: +- `vector: [.1, .2, .3]` +- `vector: { $binary: '' }` +- `vector: new DataAPIVector([.1, .2, .3])` +- `vector: vector([.1, .2, .3])` + +However, keep in mind that when `find`-ing, the `$vector` will _always_ be returned as a `DataAPIVector`, to smooth the difference between the underlying representations. + +Also, there will be a performance penalty for using plain `number[]`s instead of the binary-optimizing `DataAPIVector`. + +```typescript +const row = await table.findOne(); +console.log(row.$vector instanceof DataAPIVector); // true +``` + +You can create a `DataAPIVector` through the constructor function, or through the `vector` shorthand, by providing the vector in four different ways: +1. As an array of numbers (`[.1, .2, .3]`) +2. In its "binary" representation (`{ $binary: '' }`) +3. As a `Float32Array` (`new Float32Array([.1, .2, .3])`) +4. As a `DataAPIVector`, which copies its internal state into a new `DataAPIVector` + +From the `DataAPIVector` class, you can either: +- Get the length of the vector (in O(1) time) using `.length` +- Get the "raw" underlying vector using `.raw()` +- Get the vector in your desired format (converting if necessary) using one of: + - `.asArray()` + - `.asFloat32Array()` + - `.asBase64()` + +## Inserting native representations + +Each of the given types can be inserted into the database using their native representation—e.g: + +```typescript +await table.insertOne({ + blob: { $binary: '' }, + date: '1992-05-28', + float: 'NaN', + uuid: 'f47ac10b-58cc-4372-a567-0e02b2c3d479', + vector: [.1, .2, .3], +}); + +await collection.insertOne({ + date: { $date: 1734070574056 }, + uuid: { $uuid: 'f47ac10b-58cc-4372-a567-0e02b2c3d479' }, + oid: { $objectId: '507f1f77bcf86cd799439011' }, + $vector: [.1, .2, .3], +}); +``` + +However, it's generally recommended to use the provided classes for better type-safety and ease of use. + +Plus, importantly, when reading back, each datatype will be deserialized into their respective classes, regardless of how they were inserted. + +If you really want to change the behavior of how a certain type is deserialized, you'll need to implement some custom ser/des logic for that type. + +## Cheatsheet + +### Collections + +| Type | Type | Shorthand | Examples | +|-------------|-----------------|-----------|----------------------------------------------------------------| +| `$date` | `Date` | - | `new Date()` | +| `$uuid` | `UUID` | `uuid` | `new UUID('...')`, `UUID.v4()`, `uuid('...')`, `uuid(7)` | +| `$objectId` | `ObjectId` | `oid` | `new ObjectId()`, `new ObjectId('...')`, `oid()`, `oid('...')` | +| `$vector` | `DataAPIVector` | `vector` | `new DataAPIVector([.1, .2, .3])`, `vector([.1, .2, .3])` | + +### Tables + +| Type | Type | Shorthand | Examples | +|-------------|--------------------|-------------|--------------------------------------------------------------------------------------| +| `ascii` | `string` | - | `'Hello!'` | +| `bigint` | `number` | - | `42` | +| `blob` | `DataAPIBlob` | `blob` | `new DataAPIBlob(Buffer.from(...))`, `blob({ $binary: '' })` | +| `boolean` | `boolean` | - | `true` | +| `date` | `DataAPIDate` | `date` | `new DataAPIDate()`, `date(new Date(1734070574056))`, `date('1992-05-28')`, `date()` | +| `decimal` | `BigNumber` | - | `new BigNumber(123.4567)`, `BigNumber('123456.7e-3')` | +| `double` | `number` | - | `3.14`, `NaN`, `Infinity`, `-Infinity` | +| `duration` | `DataAPIDuration` | `duration` | `new DataAPIDuration('3w')`, `duration('P5DT30M')` | +| `float` | `number` | - | `3.14`, `NaN`, `Infinity`, `-Infinity` | +| `inet`. | `InetAddress` | `inet` | `new InetAddress('::1')`, `inet('127.0.0.1')` | +| `int` | `number` | - | `42` | +| `list` | `Array` | - | `['value']` | +| `map` | `Map` | - | `new Map([['key', 'value']])` | +| `set` | `Set` | - | `new Set(['value'])` | +| `smallint` | `number` | - | `42` | +| `text` | `string` | - | `'Hello!'` | +| `time` | `DataAPITime` | `time` | `new DataAPITime()`, `time(new Date(1734070574056))`, `time('12:34:56')`, `time()` | +| `timestamp` | `DataAPITimestamp` | `timestamp` | `new DataAPITimestamp('...')`, `timestamp(new Date(1734070574056))`, `timestamp()` | +| `timeuuid` | `UUID` | `timeuuid` | `new UUID('...')`, `UUID.v1()`, `uuid('...')`, `uuid(1)` | +| `tinyint` | `number` | - | `42` | +| `uuid` | `UUID` | `uuid` | `new UUID('...')`, `UUID.v4()`, `uuid('...')`, `uuid(7)` | +| `varchar` | `string` | - | `'Hello!'` | +| `varint` | `bigint` | - | `BigInt('42')`, `42n` | +| `vector` | `DataAPIVector` | `vector` | `new DataAPIVector([.1, .2, .3])`, `vector([.1, .2, .3])` | diff --git a/etc/imgs/class-hierarchy.png b/etc/imgs/class-hierarchy.png deleted file mode 100644 index 656b9e88..00000000 Binary files a/etc/imgs/class-hierarchy.png and /dev/null differ diff --git a/examples/browser/package-lock.json b/examples/browser/package-lock.json index b0633a16..3cf7d088 100644 --- a/examples/browser/package-lock.json +++ b/examples/browser/package-lock.json @@ -8,7 +8,7 @@ "name": "browser", "version": "0.0.0", "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "events": "^3.3.0" }, "devDependencies": { @@ -17,18 +17,20 @@ } }, "node_modules/@datastax/astra-db-ts": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-1.5.0.tgz", - "integrity": "sha512-Z9pEVyyHfglh8XAKrIASxdvORdei4pLUKDDGarqYvBkA9B9rKdqqdN+4I42Dz8paU5uscu8FwM5mc+Ly/U6jfA==", + "version": "2.0.0-preview.0", + "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-2.0.0-preview.0.tgz", + "integrity": "sha512-lqp/T+q7ByFBBFV5xOv9wYJR+45W7M5LHxaug4KFWs7LcJz5RcsVrlY/ubBOkVZiq3BdwqeETGbErUmCS2bhZg==", "license": "Apache-2.0", "dependencies": { + "bignumber.js": "^9.1.2", "fetch-h2": "^3.0.2", + "json-bigint": "^1.0.0", "safe-stable-stringify": "^2.4.3", "typed-emitter": "^2.1.0", "uuidv7": "^0.6.3" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.0.0" } }, "node_modules/@esbuild/aix-ppc64": { @@ -625,6 +627,15 @@ "integrity": "sha512-qk6RIVMS/R1yTvBzfIL1T76PsIL7DIVCINoLuFw2YXKLpLtsTobqdChMs8m3OhuPS3CEE3+Ra5ibYiqdyogbsQ==", "license": "MIT" }, + "node_modules/bignumber.js": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.2.tgz", + "integrity": "sha512-2/mKyZH9K85bzOEfhXDBFZTGd1CTs+5IHpeFQo9luiBG7hghdC851Pj2WAhb6E3R6b9tZj/XKhbg4fum+Kepug==", + "license": "MIT", + "engines": { + "node": "*" + } + }, "node_modules/callguard": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/callguard/-/callguard-2.0.0.tgz", @@ -727,6 +738,15 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, "node_modules/nanoid": { "version": "3.3.7", "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.7.tgz", diff --git a/examples/browser/package.json b/examples/browser/package.json index e1b2eb95..9cd14d00 100644 --- a/examples/browser/package.json +++ b/examples/browser/package.json @@ -13,7 +13,7 @@ "vite": "^5.2.0" }, "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "events": "^3.3.0" } } diff --git a/examples/cloudflare-workers/package-lock.json b/examples/cloudflare-workers/package-lock.json index 4583dc1b..8f50ab32 100644 --- a/examples/cloudflare-workers/package-lock.json +++ b/examples/cloudflare-workers/package-lock.json @@ -8,7 +8,7 @@ "name": "cloudflare-workers-example", "version": "0.0.0", "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "events": "^3.3.0" }, "devDependencies": { @@ -48,18 +48,20 @@ } }, "node_modules/@datastax/astra-db-ts": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-1.5.0.tgz", - "integrity": "sha512-Z9pEVyyHfglh8XAKrIASxdvORdei4pLUKDDGarqYvBkA9B9rKdqqdN+4I42Dz8paU5uscu8FwM5mc+Ly/U6jfA==", + "version": "2.0.0-preview.0", + "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-2.0.0-preview.0.tgz", + "integrity": "sha512-lqp/T+q7ByFBBFV5xOv9wYJR+45W7M5LHxaug4KFWs7LcJz5RcsVrlY/ubBOkVZiq3BdwqeETGbErUmCS2bhZg==", "license": "Apache-2.0", "dependencies": { + "bignumber.js": "^9.1.2", "fetch-h2": "^3.0.2", + "json-bigint": "^1.0.0", "safe-stable-stringify": "^2.4.3", "typed-emitter": "^2.1.0", "uuidv7": "^0.6.3" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.0.0" } }, "node_modules/@esbuild-plugins/node-globals-polyfill": { @@ -544,6 +546,15 @@ "printable-characters": "^1.0.42" } }, + "node_modules/bignumber.js": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.2.tgz", + "integrity": "sha512-2/mKyZH9K85bzOEfhXDBFZTGd1CTs+5IHpeFQo9luiBG7hghdC851Pj2WAhb6E3R6b9tZj/XKhbg4fum+Kepug==", + "license": "MIT", + "engines": { + "node": "*" + } + }, "node_modules/binary-extensions": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz", @@ -880,6 +891,15 @@ "node": ">=0.12.0" } }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, "node_modules/mime": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz", diff --git a/examples/cloudflare-workers/package.json b/examples/cloudflare-workers/package.json index 7d301be3..a80919e3 100644 --- a/examples/cloudflare-workers/package.json +++ b/examples/cloudflare-workers/package.json @@ -12,7 +12,7 @@ "wrangler": "^3.55.0" }, "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "events": "^3.3.0" } } diff --git a/examples/http2-when-minified/package-lock.json b/examples/http2-when-minified/package-lock.json index ff01b721..2eebffb8 100644 --- a/examples/http2-when-minified/package-lock.json +++ b/examples/http2-when-minified/package-lock.json @@ -8,7 +8,7 @@ "name": "nextjs-edge", "version": "0.1.0", "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "fetch-h2": "^3.0.0", "next": "14.2.3", "react": "^18", @@ -22,18 +22,20 @@ } }, "node_modules/@datastax/astra-db-ts": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-1.5.0.tgz", - "integrity": "sha512-Z9pEVyyHfglh8XAKrIASxdvORdei4pLUKDDGarqYvBkA9B9rKdqqdN+4I42Dz8paU5uscu8FwM5mc+Ly/U6jfA==", + "version": "2.0.0-preview.0", + "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-2.0.0-preview.0.tgz", + "integrity": "sha512-lqp/T+q7ByFBBFV5xOv9wYJR+45W7M5LHxaug4KFWs7LcJz5RcsVrlY/ubBOkVZiq3BdwqeETGbErUmCS2bhZg==", "license": "Apache-2.0", "dependencies": { + "bignumber.js": "^9.1.2", "fetch-h2": "^3.0.2", + "json-bigint": "^1.0.0", "safe-stable-stringify": "^2.4.3", "typed-emitter": "^2.1.0", "uuidv7": "^0.6.3" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.0.0" } }, "node_modules/@next/env": { @@ -236,6 +238,15 @@ "resolved": "https://registry.npmjs.org/already/-/already-2.2.1.tgz", "integrity": "sha512-qk6RIVMS/R1yTvBzfIL1T76PsIL7DIVCINoLuFw2YXKLpLtsTobqdChMs8m3OhuPS3CEE3+Ra5ibYiqdyogbsQ==" }, + "node_modules/bignumber.js": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.2.tgz", + "integrity": "sha512-2/mKyZH9K85bzOEfhXDBFZTGd1CTs+5IHpeFQo9luiBG7hghdC851Pj2WAhb6E3R6b9tZj/XKhbg4fum+Kepug==", + "license": "MIT", + "engines": { + "node": "*" + } + }, "node_modules/busboy": { "version": "1.6.0", "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz", @@ -325,6 +336,15 @@ "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==" }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, "node_modules/loose-envify": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz", diff --git a/examples/http2-when-minified/package.json b/examples/http2-when-minified/package.json index 7a666a40..bea58f49 100644 --- a/examples/http2-when-minified/package.json +++ b/examples/http2-when-minified/package.json @@ -9,7 +9,7 @@ "lint": "next lint" }, "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "fetch-h2": "^3.0.0", "next": "14.2.3", "react": "^18", diff --git a/examples/nextjs/package-lock.json b/examples/nextjs/package-lock.json index 35adbb77..42ae9c20 100644 --- a/examples/nextjs/package-lock.json +++ b/examples/nextjs/package-lock.json @@ -8,7 +8,7 @@ "name": "nextjs-edge", "version": "0.1.0", "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "next": "14.2.3", "react": "^18", "react-dom": "^18" @@ -21,18 +21,20 @@ } }, "node_modules/@datastax/astra-db-ts": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-1.5.0.tgz", - "integrity": "sha512-Z9pEVyyHfglh8XAKrIASxdvORdei4pLUKDDGarqYvBkA9B9rKdqqdN+4I42Dz8paU5uscu8FwM5mc+Ly/U6jfA==", + "version": "2.0.0-preview.0", + "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-2.0.0-preview.0.tgz", + "integrity": "sha512-lqp/T+q7ByFBBFV5xOv9wYJR+45W7M5LHxaug4KFWs7LcJz5RcsVrlY/ubBOkVZiq3BdwqeETGbErUmCS2bhZg==", "license": "Apache-2.0", "dependencies": { + "bignumber.js": "^9.1.2", "fetch-h2": "^3.0.2", + "json-bigint": "^1.0.0", "safe-stable-stringify": "^2.4.3", "typed-emitter": "^2.1.0", "uuidv7": "^0.6.3" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.0.0" } }, "node_modules/@next/env": { @@ -235,6 +237,15 @@ "integrity": "sha512-qk6RIVMS/R1yTvBzfIL1T76PsIL7DIVCINoLuFw2YXKLpLtsTobqdChMs8m3OhuPS3CEE3+Ra5ibYiqdyogbsQ==", "license": "MIT" }, + "node_modules/bignumber.js": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.2.tgz", + "integrity": "sha512-2/mKyZH9K85bzOEfhXDBFZTGd1CTs+5IHpeFQo9luiBG7hghdC851Pj2WAhb6E3R6b9tZj/XKhbg4fum+Kepug==", + "license": "MIT", + "engines": { + "node": "*" + } + }, "node_modules/busboy": { "version": "1.6.0", "resolved": "https://registry.npmjs.org/busboy/-/busboy-1.6.0.tgz", @@ -328,6 +339,15 @@ "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==" }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, "node_modules/loose-envify": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz", diff --git a/examples/nextjs/package.json b/examples/nextjs/package.json index 11ef71b7..489f871b 100644 --- a/examples/nextjs/package.json +++ b/examples/nextjs/package.json @@ -9,7 +9,7 @@ "lint": "next lint" }, "dependencies": { - "@datastax/astra-db-ts": "^1.5.0", + "@datastax/astra-db-ts": "^2.0.0-preview.0", "next": "14.2.3", "react": "^18", "react-dom": "^18" diff --git a/examples/non-astra-backends/package-lock.json b/examples/non-astra-backends/package-lock.json index 9cb7e908..08aa3d92 100644 --- a/examples/non-astra-backends/package-lock.json +++ b/examples/non-astra-backends/package-lock.json @@ -9,25 +9,27 @@ "version": "1.0.0", "license": "ISC", "dependencies": { - "@datastax/astra-db-ts": "^1.5.0" + "@datastax/astra-db-ts": "^2.0.0-preview.0" }, "devDependencies": { "typescript": "^5.5.2" } }, "node_modules/@datastax/astra-db-ts": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-1.5.0.tgz", - "integrity": "sha512-Z9pEVyyHfglh8XAKrIASxdvORdei4pLUKDDGarqYvBkA9B9rKdqqdN+4I42Dz8paU5uscu8FwM5mc+Ly/U6jfA==", + "version": "2.0.0-preview.0", + "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-2.0.0-preview.0.tgz", + "integrity": "sha512-lqp/T+q7ByFBBFV5xOv9wYJR+45W7M5LHxaug4KFWs7LcJz5RcsVrlY/ubBOkVZiq3BdwqeETGbErUmCS2bhZg==", "license": "Apache-2.0", "dependencies": { + "bignumber.js": "^9.1.2", "fetch-h2": "^3.0.2", + "json-bigint": "^1.0.0", "safe-stable-stringify": "^2.4.3", "typed-emitter": "^2.1.0", "uuidv7": "^0.6.3" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.0.0" } }, "node_modules/@types/tough-cookie": { @@ -42,6 +44,15 @@ "integrity": "sha512-qk6RIVMS/R1yTvBzfIL1T76PsIL7DIVCINoLuFw2YXKLpLtsTobqdChMs8m3OhuPS3CEE3+Ra5ibYiqdyogbsQ==", "license": "MIT" }, + "node_modules/bignumber.js": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.2.tgz", + "integrity": "sha512-2/mKyZH9K85bzOEfhXDBFZTGd1CTs+5IHpeFQo9luiBG7hghdC851Pj2WAhb6E3R6b9tZj/XKhbg4fum+Kepug==", + "license": "MIT", + "engines": { + "node": "*" + } + }, "node_modules/callguard": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/callguard/-/callguard-2.0.0.tgz", @@ -84,6 +95,15 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, "node_modules/psl": { "version": "1.15.0", "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz", diff --git a/examples/non-astra-backends/package.json b/examples/non-astra-backends/package.json index b855b422..7dbb649f 100644 --- a/examples/non-astra-backends/package.json +++ b/examples/non-astra-backends/package.json @@ -13,6 +13,6 @@ "typescript": "^5.5.2" }, "dependencies": { - "@datastax/astra-db-ts": "^1.5.0" + "@datastax/astra-db-ts": "^2.0.0-preview.0" } } diff --git a/examples/serdes/package-lock.json b/examples/serdes/package-lock.json index 0544537b..012e3ad5 100644 --- a/examples/serdes/package-lock.json +++ b/examples/serdes/package-lock.json @@ -9,7 +9,7 @@ "version": "1.0.0", "license": "ISC", "dependencies": { - "@datastax/astra-db-ts": "^1.5.0" + "@datastax/astra-db-ts": "^2.0.0-preview.0" }, "devDependencies": { "dotenv": "^16.4.5", @@ -18,18 +18,20 @@ } }, "node_modules/@datastax/astra-db-ts": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-1.5.0.tgz", - "integrity": "sha512-Z9pEVyyHfglh8XAKrIASxdvORdei4pLUKDDGarqYvBkA9B9rKdqqdN+4I42Dz8paU5uscu8FwM5mc+Ly/U6jfA==", + "version": "2.0.0-preview.0", + "resolved": "https://registry.npmjs.org/@datastax/astra-db-ts/-/astra-db-ts-2.0.0-preview.0.tgz", + "integrity": "sha512-lqp/T+q7ByFBBFV5xOv9wYJR+45W7M5LHxaug4KFWs7LcJz5RcsVrlY/ubBOkVZiq3BdwqeETGbErUmCS2bhZg==", "license": "Apache-2.0", "dependencies": { + "bignumber.js": "^9.1.2", "fetch-h2": "^3.0.2", + "json-bigint": "^1.0.0", "safe-stable-stringify": "^2.4.3", "typed-emitter": "^2.1.0", "uuidv7": "^0.6.3" }, "engines": { - "node": ">=14.0.0" + "node": ">=18.0.0" } }, "node_modules/@esbuild/aix-ppc64": { @@ -452,6 +454,15 @@ "integrity": "sha512-qk6RIVMS/R1yTvBzfIL1T76PsIL7DIVCINoLuFw2YXKLpLtsTobqdChMs8m3OhuPS3CEE3+Ra5ibYiqdyogbsQ==", "license": "MIT" }, + "node_modules/bignumber.js": { + "version": "9.1.2", + "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.1.2.tgz", + "integrity": "sha512-2/mKyZH9K85bzOEfhXDBFZTGd1CTs+5IHpeFQo9luiBG7hghdC851Pj2WAhb6E3R6b9tZj/XKhbg4fum+Kepug==", + "license": "MIT", + "engines": { + "node": "*" + } + }, "node_modules/callguard": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/callguard/-/callguard-2.0.0.tgz", @@ -575,6 +586,15 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, + "node_modules/json-bigint": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", + "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", + "license": "MIT", + "dependencies": { + "bignumber.js": "^9.0.0" + } + }, "node_modules/psl": { "version": "1.15.0", "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz", diff --git a/examples/serdes/package.json b/examples/serdes/package.json index 5dc75c26..beb54472 100644 --- a/examples/serdes/package.json +++ b/examples/serdes/package.json @@ -16,6 +16,6 @@ "typescript": "^5.6.3" }, "dependencies": { - "@datastax/astra-db-ts": "^1.5.0" + "@datastax/astra-db-ts": "^2.0.0-preview.0" } } diff --git a/package-lock.json b/package-lock.json index ae723a99..3c97fd4c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -364,21 +364,23 @@ } }, "node_modules/@eslint-community/regexpp": { - "version": "4.11.1", - "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.11.1.tgz", - "integrity": "sha512-m4DVN9ZqskZoLU5GlWZadwDnYo3vAEydiUayB9widCl9ffWx2IvPnp6n3on5rJmziJSw9Bv+Z3ChDVdMwXCY8Q==", + "version": "4.12.1", + "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.12.1.tgz", + "integrity": "sha512-CCZCDJuduB9OUkFkY2IgppNZMi2lBQgD2qzwXkEia16cge2pijY/aXi96CJMquDMn3nJdlPV1A5KrJEXwfLNzQ==", "dev": true, + "license": "MIT", "engines": { "node": "^12.0.0 || ^14.0.0 || >=16.0.0" } }, "node_modules/@eslint/config-array": { - "version": "0.18.0", - "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.18.0.tgz", - "integrity": "sha512-fTxvnS1sRMu3+JjXwJG0j/i4RT9u4qJ+lqS/yCGap4lH4zZGzQ7tu+xZqQmcMZq5OBZDL4QRxQzRjkWcGt8IVw==", + "version": "0.19.1", + "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.19.1.tgz", + "integrity": "sha512-fo6Mtm5mWyKjA/Chy1BYTdn5mGJoDNjC7C64ug20ADsRDGrA85bN3uK3MaKbeRkRuuIEAR5N33Jr1pbm411/PA==", "dev": true, + "license": "Apache-2.0", "dependencies": { - "@eslint/object-schema": "^2.1.4", + "@eslint/object-schema": "^2.1.5", "debug": "^4.3.1", "minimatch": "^3.1.2" }, @@ -386,11 +388,25 @@ "node": "^18.18.0 || ^20.9.0 || >=21.1.0" } }, + "node_modules/@eslint/core": { + "version": "0.9.1", + "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.9.1.tgz", + "integrity": "sha512-GuUdqkyyzQI5RMIWkHhvTWLCyLo1jNK3vzkSyaExH5kHPDHcuL2VOpHjmMY+y3+NC69qAKToBqldTBgYeLSr9Q==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@types/json-schema": "^7.0.15" + }, + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + } + }, "node_modules/@eslint/eslintrc": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-3.1.0.tgz", - "integrity": "sha512-4Bfj15dVJdoy3RfZmmo86RK1Fwzn6SstsvK9JS+BaVKqC6QQQQyXekNaC+g+LKNgkQ+2VhGAzm6hO40AhMR3zQ==", + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-3.2.0.tgz", + "integrity": "sha512-grOjVNN8P3hjJn/eIETF1wwd12DdnwFDoyceUJLYYdkpbwq3nLi+4fqrTAONx7XDALqlL220wC/RHSC/QTI/0w==", "dev": true, + "license": "MIT", "dependencies": { "ajv": "^6.12.4", "debug": "^4.3.2", @@ -422,28 +438,31 @@ } }, "node_modules/@eslint/js": { - "version": "9.10.0", - "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.10.0.tgz", - "integrity": "sha512-fuXtbiP5GWIn8Fz+LWoOMVf/Jxm+aajZYkhi6CuEm4SxymFM+eUWzbO9qXT+L0iCkL5+KGYMCSGxo686H19S1g==", + "version": "9.17.0", + "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.17.0.tgz", + "integrity": "sha512-Sxc4hqcs1kTu0iID3kcZDW3JHq2a77HO9P8CP6YEA/FpH3Ll8UXE2r/86Rz9YJLKme39S9vU5OWNjC6Xl0Cr3w==", "dev": true, + "license": "MIT", "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" } }, "node_modules/@eslint/object-schema": { - "version": "2.1.4", - "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-2.1.4.tgz", - "integrity": "sha512-BsWiH1yFGjXXS2yvrf5LyuoSIIbPrGUWob917o+BTKuZ7qJdxX8aJLRxs1fS9n6r7vESrq1OUqb68dANcFXuQQ==", + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-2.1.5.tgz", + "integrity": "sha512-o0bhxnL89h5Bae5T318nFoFzGy+YE5i/gGkoPAgkmTVdRKTiv3p8JHevPiPaMwoloKfEiiaHlawCqaZMqRm+XQ==", "dev": true, + "license": "Apache-2.0", "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" } }, "node_modules/@eslint/plugin-kit": { - "version": "0.1.0", - "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.1.0.tgz", - "integrity": "sha512-autAXT203ixhqei9xt+qkYOvY8l6LAFIdT2UXc/RPNeUVfqRF1BV94GTJyVPFKT8nFM6MyVJhjLj9E8JWvf5zQ==", + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.2.4.tgz", + "integrity": "sha512-zSkKow6H5Kdm0ZUQUB2kV5JIXqoG0+uH5YADhaEHswm664N9Db8dXSi0nMJpacpMf+MyyglF1vnZohpEg5yUtg==", "dev": true, + "license": "Apache-2.0", "dependencies": { "levn": "^0.4.1" }, @@ -451,6 +470,44 @@ "node": "^18.18.0 || ^20.9.0 || >=21.1.0" } }, + "node_modules/@humanfs/core": { + "version": "0.19.1", + "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz", + "integrity": "sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=18.18.0" + } + }, + "node_modules/@humanfs/node": { + "version": "0.16.6", + "resolved": "https://registry.npmjs.org/@humanfs/node/-/node-0.16.6.tgz", + "integrity": "sha512-YuI2ZHQL78Q5HbhDiBA1X4LmYdXCKCMQIfw0pw7piHJwyREFebJUvrQN4cMssyES6x+vfUbx1CIpaQUKYdQZOw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@humanfs/core": "^0.19.1", + "@humanwhocodes/retry": "^0.3.0" + }, + "engines": { + "node": ">=18.18.0" + } + }, + "node_modules/@humanfs/node/node_modules/@humanwhocodes/retry": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.3.1.tgz", + "integrity": "sha512-JBxkERygn7Bv/GbN5Rv8Ul6LVknS+5Bp6RgDC/O8gEBU/yeH5Ui5C/OlWrTb6qct7LjjfT6Re2NxB0ln0yYybA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=18.18" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/nzakas" + } + }, "node_modules/@humanwhocodes/module-importer": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz", @@ -465,10 +522,11 @@ } }, "node_modules/@humanwhocodes/retry": { - "version": "0.3.0", - "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.3.0.tgz", - "integrity": "sha512-d2CGZR2o7fS6sWB7DG/3a95bGKQyHMACZ5aW8qGkkqQpUoZV6C0X7Pc7l4ZNMZkfNBf4VWNe9E1jRsf0G146Ew==", + "version": "0.4.1", + "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.1.tgz", + "integrity": "sha512-c7hNEllBlenFTHBky65mhq8WD2kbN9Q6gk0bTk8lSBvc554jpXSkST1iePudpt7+A/AQvuHs9EMqjHDXMY1lrA==", "dev": true, + "license": "Apache-2.0", "engines": { "node": ">=18.18" }, @@ -992,6 +1050,13 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/estree": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.6.tgz", + "integrity": "sha512-AYnb1nQyY49te+VRAVgmzfcgjYS91mY5P0TKUDCLEM+gNnA+3T6rWITXRLYCpahpqSQbN5cE+gHpnPyXjHWxcw==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/json-bigint": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/@types/json-bigint/-/json-bigint-1.0.4.tgz", @@ -999,6 +1064,13 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/json-schema": { + "version": "7.0.15", + "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz", + "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/json5": { "version": "0.0.29", "resolved": "https://registry.npmjs.org/@types/json5/-/json5-0.0.29.tgz", @@ -1262,10 +1334,11 @@ } }, "node_modules/acorn": { - "version": "8.12.1", - "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.12.1.tgz", - "integrity": "sha512-tcpGyI9zbizT9JbV6oYE477V6mTlXvvi0T0G3SNIYE2apm/G5huBa1+K89VGeovbg+jycCrfhl3ADxErOuO6Jg==", + "version": "8.14.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.0.tgz", + "integrity": "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA==", "dev": true, + "license": "MIT", "bin": { "acorn": "bin/acorn" }, @@ -1359,10 +1432,11 @@ "integrity": "sha512-qk6RIVMS/R1yTvBzfIL1T76PsIL7DIVCINoLuFw2YXKLpLtsTobqdChMs8m3OhuPS3CEE3+Ra5ibYiqdyogbsQ==" }, "node_modules/ansi-colors": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.1.tgz", - "integrity": "sha512-JoX0apGbHaUJBNl6yF+p6JAFYZ666/hhCGKN5t9QFjbJQKUU/g8MNbFDbvfrgKXvI1QpZplPOnwIo99lX/AAmA==", + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz", + "integrity": "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==", "dev": true, + "license": "MIT", "peer": true, "engines": { "node": ">=6" @@ -1479,12 +1553,13 @@ } }, "node_modules/braces": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", - "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", + "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==", "dev": true, + "license": "MIT", "dependencies": { - "fill-range": "^7.0.1" + "fill-range": "^7.1.1" }, "engines": { "node": ">=8" @@ -1704,10 +1779,11 @@ "dev": true }, "node_modules/cross-spawn": { - "version": "7.0.3", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz", - "integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==", + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", "dev": true, + "license": "MIT", "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", @@ -1718,12 +1794,13 @@ } }, "node_modules/debug": { - "version": "4.3.4", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", - "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==", + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.0.tgz", + "integrity": "sha512-6WTZ/IxCY/T6BALoZHaE4ctp9xm+Z5kY/pzYaCHRFeyVhojxlrm+46y68HA6hr0TcwEssoxNiDEUJQjfPZ/RYA==", "dev": true, + "license": "MIT", "dependencies": { - "ms": "2.1.2" + "ms": "^2.1.3" }, "engines": { "node": ">=6.0" @@ -1765,10 +1842,11 @@ } }, "node_modules/diff": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/diff/-/diff-5.0.0.tgz", - "integrity": "sha512-/VTCrvm5Z0JGty/BWHljh+BAiw3IK+2j87NGMu8Nwc/f48WoDAC395uomO9ZD117ZOBaHmkX1oyLvkVM/aIT3w==", + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.2.0.tgz", + "integrity": "sha512-uIFDxqpRZGZ6ThOk84hEfqWoHx2devRFvpTZcTHur85vImfaxUbTW9Ryh4CpCuDnToOP1CEtXKIgytHBPVff5A==", "dev": true, + "license": "BSD-3-Clause", "peer": true, "engines": { "node": ">=0.3.1" @@ -1835,28 +1913,32 @@ } }, "node_modules/eslint": { - "version": "9.10.0", - "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.10.0.tgz", - "integrity": "sha512-Y4D0IgtBZfOcOUAIQTSXBKoNGfY0REGqHJG6+Q81vNippW5YlKjHFj4soMxamKK1NXHUWuBZTLdU3Km+L/pcHw==", + "version": "9.17.0", + "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.17.0.tgz", + "integrity": "sha512-evtlNcpJg+cZLcnVKwsai8fExnqjGPicK7gnUtlNuzu+Fv9bI0aLpND5T44VLQtoMEnI57LoXO9XAkIXwohKrA==", "dev": true, + "license": "MIT", "dependencies": { "@eslint-community/eslint-utils": "^4.2.0", - "@eslint-community/regexpp": "^4.11.0", - "@eslint/config-array": "^0.18.0", - "@eslint/eslintrc": "^3.1.0", - "@eslint/js": "9.10.0", - "@eslint/plugin-kit": "^0.1.0", + "@eslint-community/regexpp": "^4.12.1", + "@eslint/config-array": "^0.19.0", + "@eslint/core": "^0.9.0", + "@eslint/eslintrc": "^3.2.0", + "@eslint/js": "9.17.0", + "@eslint/plugin-kit": "^0.2.3", + "@humanfs/node": "^0.16.6", "@humanwhocodes/module-importer": "^1.0.1", - "@humanwhocodes/retry": "^0.3.0", - "@nodelib/fs.walk": "^1.2.8", + "@humanwhocodes/retry": "^0.4.1", + "@types/estree": "^1.0.6", + "@types/json-schema": "^7.0.15", "ajv": "^6.12.4", "chalk": "^4.0.0", - "cross-spawn": "^7.0.2", + "cross-spawn": "^7.0.6", "debug": "^4.3.2", "escape-string-regexp": "^4.0.0", - "eslint-scope": "^8.0.2", - "eslint-visitor-keys": "^4.0.0", - "espree": "^10.1.0", + "eslint-scope": "^8.2.0", + "eslint-visitor-keys": "^4.2.0", + "espree": "^10.3.0", "esquery": "^1.5.0", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", @@ -1866,14 +1948,11 @@ "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", - "is-path-inside": "^3.0.3", "json-stable-stringify-without-jsonify": "^1.0.1", "lodash.merge": "^4.6.2", "minimatch": "^3.1.2", "natural-compare": "^1.4.0", - "optionator": "^0.9.3", - "strip-ansi": "^6.0.1", - "text-table": "^0.2.0" + "optionator": "^0.9.3" }, "bin": { "eslint": "bin/eslint.js" @@ -1894,10 +1973,11 @@ } }, "node_modules/eslint-scope": { - "version": "8.0.2", - "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.0.2.tgz", - "integrity": "sha512-6E4xmrTw5wtxnLA5wYL3WDfhZ/1bUBGOXV0zQvVRDOtrR8D0p6W7fs3JweNYhwRYeGvd/1CKX2se0/2s7Q/nJA==", + "version": "8.2.0", + "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.2.0.tgz", + "integrity": "sha512-PHlWUfG6lvPc3yvP5A4PNyBL1W8fkDUccmI21JUu/+GKZBoH/W5u6usENXUrWFRsyoW5ACUjFGgAFQp5gUlb/A==", "dev": true, + "license": "BSD-2-Clause", "dependencies": { "esrecurse": "^4.3.0", "estraverse": "^5.2.0" @@ -1983,10 +2063,11 @@ } }, "node_modules/eslint/node_modules/eslint-visitor-keys": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.0.0.tgz", - "integrity": "sha512-OtIRv/2GyiF6o/d8K7MYKKbXrOUBIK6SfkIRM4Z0dY3w+LiQ0vy3F57m0Z71bjbyeiWFiHJ8brqnmE6H6/jEuw==", + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz", + "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==", "dev": true, + "license": "Apache-2.0", "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" }, @@ -2028,14 +2109,15 @@ } }, "node_modules/espree": { - "version": "10.1.0", - "resolved": "https://registry.npmjs.org/espree/-/espree-10.1.0.tgz", - "integrity": "sha512-M1M6CpiE6ffoigIOWYO9UDP8TMUw9kqb21tf+08IgDYjCsOvCuDt4jQcZmoYxx+w7zlKw9/N0KXfto+I8/FrXA==", + "version": "10.3.0", + "resolved": "https://registry.npmjs.org/espree/-/espree-10.3.0.tgz", + "integrity": "sha512-0QYC8b24HWY8zjRnDTL6RiHfDbAWn63qb4LMj1Z4b076A4une81+z03Kg7l7mn/48PUTqoLptSXez8oknU8Clg==", "dev": true, + "license": "BSD-2-Clause", "dependencies": { - "acorn": "^8.12.0", + "acorn": "^8.14.0", "acorn-jsx": "^5.3.2", - "eslint-visitor-keys": "^4.0.0" + "eslint-visitor-keys": "^4.2.0" }, "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -2045,10 +2127,11 @@ } }, "node_modules/espree/node_modules/eslint-visitor-keys": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.0.0.tgz", - "integrity": "sha512-OtIRv/2GyiF6o/d8K7MYKKbXrOUBIK6SfkIRM4Z0dY3w+LiQ0vy3F57m0Z71bjbyeiWFiHJ8brqnmE6H6/jEuw==", + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz", + "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==", "dev": true, + "license": "Apache-2.0", "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" }, @@ -2086,6 +2169,7 @@ "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz", "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==", "dev": true, + "license": "BSD-2-Clause", "dependencies": { "estraverse": "^5.2.0" }, @@ -2191,10 +2275,11 @@ } }, "node_modules/fill-range": { - "version": "7.0.1", - "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", - "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz", + "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==", "dev": true, + "license": "MIT", "dependencies": { "to-regex-range": "^5.0.1" }, @@ -2663,19 +2748,11 @@ "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", "dev": true, + "license": "MIT", "engines": { "node": ">=0.12.0" } }, - "node_modules/is-path-inside": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/is-path-inside/-/is-path-inside-3.0.3.tgz", - "integrity": "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ==", - "dev": true, - "engines": { - "node": ">=8" - } - }, "node_modules/is-plain-obj": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-2.1.0.tgz", @@ -3164,12 +3241,13 @@ } }, "node_modules/micromatch": { - "version": "4.0.5", - "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", - "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz", + "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==", "dev": true, + "license": "MIT", "dependencies": { - "braces": "^3.0.2", + "braces": "^3.0.3", "picomatch": "^2.3.1" }, "engines": { @@ -3198,33 +3276,33 @@ } }, "node_modules/mocha": { - "version": "10.2.0", - "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.2.0.tgz", - "integrity": "sha512-IDY7fl/BecMwFHzoqF2sg/SHHANeBoMMXFlS9r0OXKDssYE1M5O43wUY/9BVPeIvfH2zmEbBfseqN9gBQZzXkg==", + "version": "10.8.2", + "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.8.2.tgz", + "integrity": "sha512-VZlYo/WE8t1tstuRmqgeyBgCbJc/lEdopaa+axcKzTBJ+UIdlAB9XnmvTCAH4pwR4ElNInaedhEBmZD8iCSVEg==", "dev": true, + "license": "MIT", "peer": true, "dependencies": { - "ansi-colors": "4.1.1", - "browser-stdout": "1.3.1", - "chokidar": "3.5.3", - "debug": "4.3.4", - "diff": "5.0.0", - "escape-string-regexp": "4.0.0", - "find-up": "5.0.0", - "glob": "7.2.0", - "he": "1.2.0", - "js-yaml": "4.1.0", - "log-symbols": "4.1.0", - "minimatch": "5.0.1", - "ms": "2.1.3", - "nanoid": "3.3.3", - "serialize-javascript": "6.0.0", - "strip-json-comments": "3.1.1", - "supports-color": "8.1.1", - "workerpool": "6.2.1", - "yargs": "16.2.0", - "yargs-parser": "20.2.4", - "yargs-unparser": "2.0.0" + "ansi-colors": "^4.1.3", + "browser-stdout": "^1.3.1", + "chokidar": "^3.5.3", + "debug": "^4.3.5", + "diff": "^5.2.0", + "escape-string-regexp": "^4.0.0", + "find-up": "^5.0.0", + "glob": "^8.1.0", + "he": "^1.2.0", + "js-yaml": "^4.1.0", + "log-symbols": "^4.1.0", + "minimatch": "^5.1.6", + "ms": "^2.1.3", + "serialize-javascript": "^6.0.2", + "strip-json-comments": "^3.1.1", + "supports-color": "^8.1.1", + "workerpool": "^6.5.1", + "yargs": "^16.2.0", + "yargs-parser": "^20.2.9", + "yargs-unparser": "^2.0.0" }, "bin": { "_mocha": "bin/_mocha", @@ -3232,10 +3310,17 @@ }, "engines": { "node": ">= 14.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/mochajs" + } + }, + "node_modules/mocha/node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "license": "MIT", + "peer": true, + "dependencies": { + "balanced-match": "^1.0.0" } }, "node_modules/mocha/node_modules/escape-string-regexp": { @@ -3252,39 +3337,27 @@ } }, "node_modules/mocha/node_modules/glob": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", - "integrity": "sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==", + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/glob/-/glob-8.1.0.tgz", + "integrity": "sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ==", + "deprecated": "Glob versions prior to v9 are no longer supported", "dev": true, + "license": "ISC", "peer": true, "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", - "minimatch": "^3.0.4", - "once": "^1.3.0", - "path-is-absolute": "^1.0.0" + "minimatch": "^5.0.1", + "once": "^1.3.0" }, "engines": { - "node": "*" + "node": ">=12" }, "funding": { "url": "https://github.com/sponsors/isaacs" } }, - "node_modules/mocha/node_modules/glob/node_modules/minimatch": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", - "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", - "dev": true, - "peer": true, - "dependencies": { - "brace-expansion": "^1.1.7" - }, - "engines": { - "node": "*" - } - }, "node_modules/mocha/node_modules/has-flag": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", @@ -3296,10 +3369,11 @@ } }, "node_modules/mocha/node_modules/minimatch": { - "version": "5.0.1", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.0.1.tgz", - "integrity": "sha512-nLDxIFRyhDblz3qMuq+SoRZED4+miJ/G+tdDrjkkkRnjAsBexeGpgjLEQ0blJy7rHhR2b93rhQY4SvyWu9v03g==", + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz", + "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==", "dev": true, + "license": "ISC", "peer": true, "dependencies": { "brace-expansion": "^2.0.1" @@ -3308,23 +3382,6 @@ "node": ">=10" } }, - "node_modules/mocha/node_modules/minimatch/node_modules/brace-expansion": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", - "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", - "dev": true, - "peer": true, - "dependencies": { - "balanced-match": "^1.0.0" - } - }, - "node_modules/mocha/node_modules/ms": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "dev": true, - "peer": true - }, "node_modules/mocha/node_modules/supports-color": { "version": "8.1.1", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", @@ -3342,10 +3399,11 @@ } }, "node_modules/ms": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", - "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==", - "dev": true + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" }, "node_modules/mylas": { "version": "2.1.13", @@ -3360,19 +3418,6 @@ "url": "https://github.com/sponsors/raouldeheer" } }, - "node_modules/nanoid": { - "version": "3.3.3", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.3.tgz", - "integrity": "sha512-p1sjXuopFs0xg+fPASzQ28agW1oHD7xDsd9Xkf3T15H3c/cifrFHVwrh74PdoklAPi+i7MdRsE47vm2r6JoB+w==", - "dev": true, - "peer": true, - "bin": { - "nanoid": "bin/nanoid.cjs" - }, - "engines": { - "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" - } - }, "node_modules/natural-compare": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz", @@ -3941,6 +3986,7 @@ "resolved": "https://registry.npmjs.org/randombytes/-/randombytes-2.1.0.tgz", "integrity": "sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==", "dev": true, + "license": "MIT", "peer": true, "dependencies": { "safe-buffer": "^5.1.0" @@ -4133,10 +4179,11 @@ } }, "node_modules/serialize-javascript": { - "version": "6.0.0", - "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.0.tgz", - "integrity": "sha512-Qr3TosvguFt8ePWqsvRfrKyQXIiW+nGbYpy8XK24NQHE83caxWt+mIymTT19DGFbNWNLfEwsrkSmN64lVWB9ag==", + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.2.tgz", + "integrity": "sha512-Saa1xPByTTq2gdeFZYLLo+RFE35NHZkAbqZeWNd3BpzppeVisAqpDjcp8dyf6uIvEqJRd46jemmyA4iFIeVk8g==", "dev": true, + "license": "BSD-3-Clause", "peer": true, "dependencies": { "randombytes": "^2.1.0" @@ -4344,12 +4391,6 @@ "node": ">=8" } }, - "node_modules/text-table": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz", - "integrity": "sha512-N+8UisAXDGk8PFXP4HAzVR9nbfmVJ3zYLAWiTIoqC5v5isinhr+r5uaO8+7r3BMfuNIufIsA7RdpVgacC2cSpw==", - "dev": true - }, "node_modules/through2": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/through2/-/through2-4.0.2.tgz", @@ -4377,6 +4418,7 @@ "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", "dev": true, + "license": "MIT", "dependencies": { "is-number": "^7.0.0" }, @@ -4741,10 +4783,11 @@ } }, "node_modules/workerpool": { - "version": "6.2.1", - "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.2.1.tgz", - "integrity": "sha512-ILEIE97kDZvF9Wb9f6h5aXK4swSlKGUcOEGiIYb2OOu/IrDU9iwj0fD//SsA6E5ibwJxpEvhullJY4Sl4GcpAw==", + "version": "6.5.1", + "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.5.1.tgz", + "integrity": "sha512-Fs4dNYcsdpYSAfVxhnl1L5zTksjvOJxtC5hzMNl+1t9B8hTJTdKDyZ5ju7ztgPy+ft9tBFXoOlDNiOT9WUXZlA==", "dev": true, + "license": "Apache-2.0", "peer": true }, "node_modules/wrap-ansi": { @@ -4855,10 +4898,11 @@ } }, "node_modules/yargs-parser": { - "version": "20.2.4", - "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.4.tgz", - "integrity": "sha512-WOkpgNhPTlE73h4VFAFsOnomJVaovO8VqLDzy5saChRBFQFBoMYirowyW+Q9HB4HFF4Z7VZTiG3iSzJJA29yRA==", + "version": "20.2.9", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz", + "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==", "dev": true, + "license": "ISC", "peer": true, "engines": { "node": ">=10" diff --git a/scripts/build.sh b/scripts/build.sh index c1af3d29..4b3a4955 100755 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -34,7 +34,7 @@ if [ "$1" != "-light" ]; then # Removes all .d.ts files except the main rollup .d.ts cd dist || return 1 -# find . -type f -name '*.d.ts' ! -name 'astra-db-ts.d.ts' -exec rm {} + + find . -type f -name '*.d.ts' ! -name 'astra-db-ts.d.ts' -exec rm {} + cd .. # Delete any empty leftover directories diff --git a/scripts/repl.sh b/scripts/repl.sh index 89474120..41dd76e6 100755 --- a/scripts/repl.sh +++ b/scripts/repl.sh @@ -64,4 +64,28 @@ node -i -e " return 'Cleared console'; }, }); + + Object.defineProperty(this, 'cdm', { + get() { + return coll.deleteMany(); + }, + }); + + Object.defineProperty(this, 'tdm', { + get() { + return table.deleteMany(); + }, + }); + + Object.defineProperty(this, 'cfa', { + get() { + return coll.find({}).toArray(); + }, + }); + + Object.defineProperty(this, 'tfa', { + get() { + return table.find({}).toArray(); + }, + }); " diff --git a/scripts/update-example-client-dep.sh b/scripts/update-example-client-dep.sh index b3209f0c..4608da69 100755 --- a/scripts/update-example-client-dep.sh +++ b/scripts/update-example-client-dep.sh @@ -13,7 +13,7 @@ npm) for dir in examples/*; do cd "$cwd/$dir" || exit 1 npm rm @datastax/astra-db-ts - npm i @datastax/astra-db-ts + npm i @datastax/astra-db-ts@next done ;; local) diff --git a/src/administration/astra-admin.ts b/src/administration/astra-admin.ts index f933000d..ddb54ea8 100644 --- a/src/administration/astra-admin.ts +++ b/src/administration/astra-admin.ts @@ -33,7 +33,7 @@ import { AdminOptions, DbOptions } from '@/src/client'; import { $CustomInspect } from '@/src/lib/constants'; import { SomeDoc } from '@/src/documents'; import { Timeouts } from '@/src/lib/api/timeouts'; -import { DropAstraDatabaseOptions } from '@/src/administration/types/admin/drop-database'; +import { AstraDropDatabaseOptions } from '@/src/administration/types/admin/drop-database'; /** * An administrative class for managing Astra databases, including creating, listing, and deleting databases. @@ -461,7 +461,7 @@ export class AstraAdmin { * * @remarks Use with caution. Wear a harness. Don't say I didn't warn you. */ - public async dropDatabase(db: Db | string, options?: DropAstraDatabaseOptions): Promise { + public async dropDatabase(db: Db | string, options?: AstraDropDatabaseOptions): Promise { const id = typeof db === 'string' ? db : db.id; const tm = this.#httpClient.tm.multipart('databaseAdminTimeoutMs', options); diff --git a/src/administration/types/admin/drop-database.ts b/src/administration/types/admin/drop-database.ts index bcc5192e..72895a8e 100644 --- a/src/administration/types/admin/drop-database.ts +++ b/src/administration/types/admin/drop-database.ts @@ -20,4 +20,4 @@ import { WithTimeout } from '@/src/lib'; * * @public */ -export type DropAstraDatabaseOptions = AstraAdminBlockingOptions & WithTimeout<'databaseAdminTimeoutMs'>; +export type AstraDropDatabaseOptions = AstraAdminBlockingOptions & WithTimeout<'databaseAdminTimeoutMs'>; diff --git a/src/administration/types/db-admin/astra-drop-keyspace.ts b/src/administration/types/db-admin/astra-drop-keyspace.ts index d68f01be..46d42545 100644 --- a/src/administration/types/db-admin/astra-drop-keyspace.ts +++ b/src/administration/types/db-admin/astra-drop-keyspace.ts @@ -16,6 +16,8 @@ import { AstraAdminBlockingOptions } from '@/src/administration/types'; import { WithTimeout } from '@/src/lib'; /** + * Represents the options for dropping an astra keyspace (i.e. blocking options + timeout options). + * * @public */ export type AstraDropKeyspaceOptions = AstraAdminBlockingOptions & WithTimeout<'keyspaceAdminTimeoutMs'>; diff --git a/src/administration/types/index.ts b/src/administration/types/index.ts index 34349450..3295b0a3 100644 --- a/src/administration/types/index.ts +++ b/src/administration/types/index.ts @@ -26,7 +26,7 @@ export type { } from './admin/create-database'; export type { - DropAstraDatabaseOptions, + AstraDropDatabaseOptions, } from './admin/drop-database'; export type { diff --git a/src/db/types/tables/create-table.ts b/src/db/types/tables/create-table.ts index 6a9b2e84..f7bfeb5b 100644 --- a/src/db/types/tables/create-table.ts +++ b/src/db/types/tables/create-table.ts @@ -56,11 +56,83 @@ export interface CreateTableDefinition { } /** + * ##### Overview + * + * Represents the syntax for defining a new column through the bespoke Data API schema definition syntax, in which there + * are two branching ways to define a column. + * + * @example + * ```ts + * await db.createTable('my_table', { + * definition: { + * columns: { + * id: 'uuid', + * name: { type: 'text' }, + * set: { type: 'set', valueType: 'text' }, + * }, + * primaryKey: ..., + * }, + * }); + * ``` + * + * ##### The "loose" column definition + * + * The loose column definition is a shorthand for the strict version, and follows the following example form: + * + * ```ts + * columns: { + * textCol: 'text', + * uuidCol: 'uuid', + * } + * ``` + * + * In this form, the key is the column name, and the value is the type of the scalar column. + * + * If you need to define a column with a more complex type (i.e. for maps, sets, lists, and vectors), you must use the strict column definition. + * + * Plus, while it still provides autocomplete, the loose column definition does not statically enforce the type of the column, whereas the strict column definition does. + * + * ##### The "strict" column definition + * + * The strict column definition is the more structured way to define a column, and follows the following example form: + * + * ```ts + * columns: { + * uuidCol: { type: 'uuid' }, + * mapCol: { type: 'map', keyType: 'text', valueType: 'int' }, + * listCol: { type: 'list', valueType: 'text' }, + * vectorCol: { type: 'vector', dimension: 3 }, + * } + * ``` + * + * In this form, the key is the column name, and the value is an object with a `type` field that specifies the type of the column. + * + * The object may also contain additional fields that are specific to the type of the column: + * - For `map`, you _must_ specify the `keyType` and `valueType` fields. + * - The `keyType` must, for the time being, be either `'text'` or `'ascii'`. + * - The `valueType` must be a scalar type. + * - For `list`s and `set`s, you _must_ specify the `valueType` field. + * - The `valueType` must be a scalar type. + * - For `vector`s, you _must_ specify the `dimension` field. + * - You may optionally provide a `service` field to enable vectorize. + * - Note that you still need to create a vector index on the column to actually use vector search. + * + * @see LooseCreateTableColumnDefinition + * @see StrictCreateTableColumnDefinition + * * @public */ export type CreateTableColumnDefinitions = Record; /** + * ##### Overview + * + * Represents the scalar types that can be used to define a column in a table. + * + * ##### Disclaimer + * + * _Note that there may be other scalar types not present in this union that have partial Data API support, but may not be created through the Data API (such as `timeuuid` or `varchar`)._ + * * @public */ export type TableScalarType = @@ -84,6 +156,23 @@ export type TableScalarType = | 'varint'; /** + * ##### Overview + * + * The loose column definition is a shorthand for the strict version, and follows the following example form: + * + * ```ts + * columns: { + * textCol: 'text', + * uuidCol: 'uuid', + * } + * ``` + * + * In this form, the key is the column name, and the value is the type of the scalar column. + * + * If you need to define a column with a more complex type (i.e. for maps, sets, lists, and vectors), you must use the strict column definition. + * + * Plus, while it still provides autocomplete, the loose column definition does not statically enforce the type of the column, whereas the strict column definition does. + * * @public */ export type LooseCreateTableColumnDefinition = @@ -91,6 +180,41 @@ export type LooseCreateTableColumnDefinition = | string; /** + * ##### Overview + * + * The strict column definition is the more structured way to define a column, and follows the following example form: + * + * ```ts + * columns: { + * uuidCol: { type: 'uuid' }, + * mapCol: { type: 'map', keyType: 'text', valueType: 'int' }, + * listCol: { type: 'list', valueType: 'text' }, + * vectorCol: { type: 'vector', dimension: 3 }, + * } + * ``` + * + * In this form, the key is the column name, and the value is an object with a `type` field that specifies the type of the column. + * + * The object may also contain additional fields that are specific to the type of the column: + * - For `map`, you _must_ specify the `keyType` and `valueType` fields. + * - The `keyType` must, for the time being, be either `'text'` or `'ascii'`. + * - The `valueType` must be a scalar type. + * - For `list`s and `set`s, you _must_ specify the `valueType` field. + * - The `valueType` must be a scalar type. + * - For `vector`s, you _must_ specify the `dimension` field. + * - You may optionally provide a `service` field to enable vectorize. + * - Note that you still need to create a vector index on the column to actually use vector search. + * + * ##### The "loose" shorthand syntax + * + * If you're simply defining a scalar column, you can use the shorthand "loose" syntax instead, which is equivalent to the above for `uuidCol`: + * + * ```ts + * columns: { + * uuidCol: 'uuid', + * } + * ``` + * * @public */ export type StrictCreateTableColumnDefinition = @@ -101,6 +225,36 @@ export type StrictCreateTableColumnDefinition = | VectorCreateTableColumnDefinition; /** + * ##### Overview + * + * Represents the "strict" column type definition for a scalar column. + * + * Of the example format: + * + * ```ts + * columns: { + * uuidCol: { type: 'uuid' }, + * textCol: { type: 'text' }, + * } + * ``` + * + * ##### The "loose" syntax + * + * If you prefer, you can use the shorthand "loose" syntax instead, which is equivalent to the above: + * + * ```ts + * columns: { + * uuidCol: 'uuid', + * textCol: 'text', + * } + * ``` + * + * The only difference is that the "loose" syntax does not statically enforce the type of the column, whereas the "strict" syntax does. + * + * However, the loose syntax still provides autocomplete for the scalar types' names. + * + * @see StrictCreateTableColumnDefinition + * * @public */ export interface ScalarCreateTableColumnDefinition { @@ -108,15 +262,91 @@ export interface ScalarCreateTableColumnDefinition { } /** + * ##### Overview + * + * Represents the syntax for defining a `map` column in a table, which has no shorthand/"loose" equivalent. + * + * Of the example format: + * + * ```ts + * columns: { + * mapCol: { type: 'map', keyType: 'text', valueType: 'int' }, + * } + * ``` + * + * This may then be used through `astra-db-ts` as a `Map`: + * + * ```ts + * await table.insertOne({ + * mapCol: new Map([['key1', 1], ['key2', 2]]), + * }); + * ``` + * + * ##### The key type + * + * The `keyType` must, for the time being, be either `'text'` or `'ascii'`. + * + * Other fields, even those which are still represented as strings in the serialized JSON form (such as `uuid`) are not supported as key types. + * + * ##### The value type + * + * The `valueType` may be any scalar type, such as `'int'`, `'text'`, or `'uuid'`. + * + * Nested collection types are not supported. + * + * @example + * ```ts + * import { uuid } from '@datastax/astra-db-ts'; + * + * await table.insertOne({ + * mapCol: new Map([['key1', uuid(4)], ['key2', uuid(4)]]); + * }); + * ``` + * * @public */ export interface MapCreateTableColumnDefinition { type: 'map', - keyType: TableScalarType, + keyType: 'text' | 'ascii', valueType: TableScalarType, } /** + * ##### Overview + * + * Represents the syntax for defining a `list` column in a table, which has no shorthand/"loose" equivalent. + * + * Of the example format: + * + * ```ts + * columns: { + * listCol: { type: 'list', valueType: 'text' }, + * } + * ``` + * + * This may then be used through `astra-db-ts` as n `Array` (aka `ValueType[]`): + * + * ```ts + * await table.insertOne({ + * listCol: ['value1', 'value2', 'value3'], + * }); + * ``` + * + * ##### The value type + * + * The `valueType` may be any scalar type, such as `'int'`, `'text'`, or `'uuid'`. + * + * Nested collection types are not supported. + * + * @example + * ```ts + * import { uuid } from '@datastax/astra-db-ts'; + * + * await table.insertOne({ + * listCol: [uuid(4), uuid(4), uuid(7)], + * }); + * ``` + * * @public */ export interface ListCreateTableColumnDefinition { @@ -125,6 +355,41 @@ export interface ListCreateTableColumnDefinition { } /** + * ##### Overview + * + * Represents the syntax for defining a `set` column in a table, which has no shorthand/"loose" equivalent. + * + * Of the example format: + * + * ```ts + * columns: { + * setCol: { type: 'set', valueType: 'text' }, + * } + * ``` + * + * This may then be used through `astra-db-ts` as n `Set`: + * + * ```ts + * await table.insertOne({ + * setCol: new Set(['value1', 'value2', 'value3']), + * }); + * ``` + * + * ##### The value type + * + * The `valueType` may be any scalar type, such as `'int'`, `'text'`, or `'uuid'`. + * + * Nested collection types are not supported. + * + * @example + * ```ts + * import { uuid } from '@datastax/astra-db-ts'; + * + * await table.insertOne({ + * setCol: new Set([uuid(4), uuid(4), uuid(7)]), + * }); + * ``` + * * @public */ export interface SetCreateTableColumnDefinition { @@ -133,27 +398,155 @@ export interface SetCreateTableColumnDefinition { } /** + * ##### Overview + * + * Represents the syntax for defining a `vector` column in a table, which has no shorthand/"loose" equivalent. + * + * Of the example format: + * + * ```ts + * columns: { + * vectorCol: { type: 'vector', dimension: 3 }, + * } + * ``` + * + * This may then be used through `astra-db-ts` as a `DataAPIVector`: + * + * ```ts + * import { vector } from '@datastax/astra-db-ts'; + * + * await table.insertOne({ + * vectorCol: vector([1, 2, 3]), + * }); + * + * // Or, if vectorize (auto-embedding-generation) is enabled: + * await table.insertOne({ + * vectorCol: 'Alice went to the beach', + * }); + * ``` + * + * Keep in mind though, that a vector index must still be created on this column (through {@link Table.createVectorIndex} or CQL directly) to enable vector search on this column. + * + * ##### The dimension + * + * The `dimension` must be a positive integer, and represents the number of elements in the vector. + * + * Note that, at the time of writing, the dimension must still be specified, even if a `service` block is present. + * + * ##### The service block + * + * You may specify the `service` block to enable vectorize (auto-embedding-generation) for the column. + * + * If this is configured, then you can pass a `string` to the vector column instead of a vector directly, and have the Data API automatically embed it for you, using the model of your choice. + * + * If the `service` field is present, then {@link InferTableSchema} will also type the column as `string | DataAPIVector | null` instead of just `DataAPIVector | null`. + * + * @see Table.createVectorIndex + * @see DataAPIVector + * * @public */ export interface VectorCreateTableColumnDefinition { type: 'vector', - dimension?: number, + dimension: number, service?: VectorizeServiceOptions, } /** + * ##### Overview + * + * Represents the syntax for defining the primary key of a table through the bespoke Data API schema definition syntax, + * in which there are two branching ways to define the primary key. + * + * @example + * ```ts + * await db.createTable('my_table', { + * definition: { + * columns: ..., + * primaryKey: { + * partitionBy: ['pt_key'], + * partitionSort: { cl_key: 1 }, + * }, + * }, + * }); + * ``` + * + * ##### The shorthand definition + * + * If your table only has a single partition key, then you can define the partition key as simply + * + * ```ts + * primaryKey: 'pt_key', + * ``` + * + * This is equivalent to the following full definition: + * + * ```ts + * primaryKey: { + * partitionBy: ['pt_key'], + * partitionSort: {}, // note that this field is also optional if it's empty + * } + * ``` + * + * ##### The full definition + * + * If your table has multiple columns in its primary key, you may use the full primary key definition syntax to express that: + * + * ```ts + * primaryKey: { + * partitionBy: ['pt_key1', 'pt_key2'], + * partitionSort: { cl_key1: 1, cl_key2: -1 }, + * } + * ``` + * + * A sort of `1` on the clustering column means ascending, and a sort of -1 means descending. + * + * Note that, if you don't have any clustering keys (partition sorts), you can omit the `partitionSort` field entirely: + * + * ```ts + * primaryKey: { + * partitionBy: ['pt_key1', 'pt_key2'], + * } + * ``` + * + * @see FullCreateTablePrimaryKeyDefinition + * * @public */ export type CreateTablePrimaryKeyDefinition = - | ShortCreateTablePrimaryKeyDefinition + | string | FullCreateTablePrimaryKeyDefinition; /** - * @public - */ -export type ShortCreateTablePrimaryKeyDefinition = string; - -/** + * ##### Overview + * + * If your table has multiple columns in its primary key, you may use the full primary key definition syntax to express that: + * + * ```ts + * primaryKey: { + * partitionBy: ['pt_key1', 'pt_key2'], + * partitionSort: { cl_key1: 1, cl_key2: -1 }, + * } + * ``` + * + * Note that, if you don't have any clustering keys (partition sorts), you can omit the `partitionSort` field entirely: + * + * ```ts + * primaryKey: { + * partitionBy: ['pt_key1', 'pt_key2'], + * } + * ``` + * + * A sort of `1` on the clustering column means ascending, and a sort of -1 means descending. + * + * ##### The shorthand syntax + * + * If your table definition only has a single partition key, and no clustering keys (partition sorts), you can use the shorthand syntax instead: + * + * ```ts + * primaryKey: 'pt_key', + * ``` + * * @public */ export interface FullCreateTablePrimaryKeyDefinition { diff --git a/src/db/types/tables/list-tables.ts b/src/db/types/tables/list-tables.ts index 836a045f..995fb4da 100644 --- a/src/db/types/tables/list-tables.ts +++ b/src/db/types/tables/list-tables.ts @@ -51,6 +51,8 @@ export interface ListTablesOptions extends WithTimeout<'tableAdminTimeoutMs'>, W /** * Information about a table, used when `nameOnly` is false in {@link ListTablesOptions}. * + * The definition is very similar to {@link CreateTableDefinition}, except for a couple key differences. See {@link ListTableDefinition} for more information. + * * @field name - The name of the tables. * @field options - The creation options for the tables. * @@ -61,16 +63,73 @@ export interface ListTablesOptions extends WithTimeout<'tableAdminTimeoutMs'>, W */ export interface TableDescriptor { /** - * The name of the tables. + * The name of the table. */ name: string, /** * The definition of the table (i.e. the `columns` and `primaryKey` fields). + * + * Very similar to {@link CreateTableDefinition}, except for a couple key differences. See {@link ListTableDefinition} for more information. */ definition: ListTableDefinition, } /** + * ##### Overview + * + * The response type of {@link Db.listTables} (without `nameOnly: true`), which is very similar to {@link CreateTableDefinition}, except + * for a couple key differences. + * + * ##### No shorthands + * + * Unlike {@link CreateTableDefinition}, `ListTableDefinition` does not return column nor primary key definitions in their shorthand notation, even if they were created with them. + * + * Instead, their full definitions are always returned, meaning, if you defined a table like so: + * + * ```ts + * const table = db.schema.createTable('my_table', { + * definition: { + * columns: { + * id: 'uuid', + * name: 'text', + * } + * primaryKey: 'id', + * } + * }); + * ``` + * + * The returned `ListTableDefinition` would look like this: + * + * ```ts + * { + * columns: { + * id: { type: 'uuid' }, + * name: { type: 'text' }, + * }, + * primaryKey: { + * partitionKey: ['id'], + * partitionSort: {}, + * }, + * } + * ``` + * + * ##### `apiSupport` + * + * If the table was created with any partially-supported or fully-unsupported types, the `apiSupport` field will be present on the column definition. + * + * If the column is unable to be created through the Data API, the column `type` will be exactly `'UNSUPPORTED'` and the `apiSupport` field will be present. + * + * However, it is possible for columns created through the Data API to also have the `apiSupport` field, if the column was created with a type that is partially unsupported. + * + * The `apiSupport` block dictates which operations are supported for the column; for example, if the column is unsupported for filtering on, the `filter` field will be `false`. Not all unsupported types are completely unusable. + * + * @field columns - The columns of the tables. + * @field primaryKey - The primary key of the tables. + * + * @see CreateTableDefinition + * @see ListTablesOptions + * @see Db.listTables + * * @public */ export interface ListTableDefinition { @@ -79,16 +138,69 @@ export interface ListTableDefinition { } /** + * ##### Overview + * + * The column definitions for a table, used in {@link ListTableDefinition}. + * + * The keys are the column names, and the values are the column definitions. + * + * ##### No shorthand + * + * Unlike {@link CreateTableDefinition}, `ListTableColumnDefinitions` does not return column definitions in their shorthand notation, even if they were created with them. + * + * See {@link ListTableDefinition} for more information. + * + * ##### `apiSupport` + * + * The column definitions may or may not include the `apiSupport` field, depending on the column's type. + * + * See {@link ListTableDefinition} for more information. + * * @public */ export type ListTableColumnDefinitions = Record; /** + * ##### Overview + * + * The column definition for a table, used in {@link ListTableColumnDefinitions}. + * + * The definition is very similar to {@link StrictCreateTableColumnDefinition}, except for the potential of having a `apiSupport` field. + * + * ##### No shorthand + * + * Unlike {@link StrictCreateTableColumnDefinition}, `ListTableKnownColumnDefinition` does not return column definitions in their shorthand notation, even if they were created with them. + * + * See {@link ListTableDefinition} for more information. + * + * ##### `apiSupport` + * + * If the column can not be created through the Data API, the column `type` will be exactly `'UNSUPPORTED'` and the `apiSupport` field will be present. See {@link ListTableUnsupportedColumnDefinition} for more information. + * + * However, it is possible for columns created through the Data API to also have the `apiSupport` field, if the column was created with a type that is partially unsupported. + * + * The `apiSupport` block dictates which operations are supported for the column; for example, if the column is unsupported for filtering on, the `filter` field will be `false`. Not all unsupported types are completely unusable. + * + * @field apiSupport - The API support for the column. + * + * @see ListTableUnsupportedColumnDefinition + * * @public */ -export type ListTableKnownColumnDefinition = StrictCreateTableColumnDefinition; +export type ListTableKnownColumnDefinition = StrictCreateTableColumnDefinition & { + apiSupport?: ListTableUnsupportedColumnApiSupport, +}; /** + * ##### Overview + * + * The column definition for a table that is unsupported by the Data API, used in {@link ListTableColumnDefinitions}. + * + * The `apiSupport` block dictates which operations are supported for the column; for example, if the column is unsupported for filtering on, the `filter` field will be `false`. Not all unsupported types are completely unusable. + * + * @field type - The type of the column, which is always `'UNSUPPORTED'`. + * @field apiSupport - The API support for the column. + * * @public */ export interface ListTableUnsupportedColumnDefinition { @@ -97,16 +209,49 @@ export interface ListTableUnsupportedColumnDefinition { } /** + * ##### Overview + * + * The API support for a column that is partially-supported or fully-unsupported by the Data API, used in {@link ListTableUnsupportedColumnDefinition}. + * + * ##### `cqlDefinition` + * + * The `cqlDefinition` column displays how the column is defined in CQL, e.g. `frozen>`. + * + * This will be present for all columns with the `apiSupport` block, regardless of whether they can be represented by the Data API or not. + * + * ##### Other fields + * + * The other fields in the `apiSupport` block dictate which operations are supported for the column; for example, if the column is unsupported for filtering on, the `filter` field will be `false`. Not all unsupported types are completely unusable. + * + * @field createTable - Whether the column can be created through the Data API. + * @field insert - Whether the column can be inserted into through the Data API. + * @field read - Whether the column can be read from through the Data API. + * @field filter - Whether the column can be filtered on through the Data API. + * @field cqlDefinition - The CQL definition of the column. + * * @public */ export interface ListTableUnsupportedColumnApiSupport { createTable: boolean, insert: boolean, read: boolean, + filter: boolean, cqlDefinition: string, } /** + * ##### Overview + * + * The primary key definition for a table, used in {@link ListTableDefinition}. + * + * The definition is very similar to {@link FullCreateTablePrimaryKeyDefinition}, except that the `partitionSort` field is always present. + * + * ##### No shorthand + * + * Unlike {@link CreateTablePrimaryKeyDefinition}, `ListTablePrimaryKeyDefinition` does not return primary key definitions in their shorthand notation, even if they were created with them. + * + * See {@link ListTableDefinition} for more information. + * * @public */ export type ListTablePrimaryKeyDefinition = Required; diff --git a/src/db/types/tables/spawn-table.ts b/src/db/types/tables/spawn-table.ts index 566838a3..053af684 100644 --- a/src/db/types/tables/spawn-table.ts +++ b/src/db/types/tables/spawn-table.ts @@ -25,6 +25,7 @@ import { DataAPILoggingConfig, type TimeoutDescriptor } from '@/src/lib'; * @field timeoutDefaults - Default timeouts for all table operations * @field logging - Logging configuration overrides * @field serdes - Additional serialization/deserialization configuration + * @field keyspace - Overrides the keyspace for the table (from the `Db`'s working keyspace). * * @public */ diff --git a/src/lib/logging/constants.ts b/src/lib/logging/constants.ts index 23299356..acde8868 100644 --- a/src/lib/logging/constants.ts +++ b/src/lib/logging/constants.ts @@ -80,6 +80,29 @@ export const DataAPILoggingDefaultOutputs = { }; /** + * ##### Overview + * + * The default logging configuration for each of the Data API events. + * + * These are used if events are "enabled" without specified outputs being provided; e.g.: + * - `logging: ['commandStarted', 'commandSucceeded', 'commandFailed']` + * - `logging: 'all'` + * + * ##### Defaults + * + * All events are emitted as events by default, through the {@link DataAPIClient}, which is an instance of an {@link EventEmitter}. + * + * Beyond that though, certain events are logged to `stdout` by default, others to `stderr`, and others not at all: + * - `adminCommandStarted`, `adminCommandPolling`, and `adminCommandSucceeded` + * - Logged to `stdout` + * - `adminCommandFailed`, `commandFailed`, `commandWarnings`, and `adminCommandWarnings` + * - Logged to `stderr` + * - `commandStarted` and `commandSucceeded` + * - Not logged at all + * + * @see DataAPIClientEventMap + * @see DataAPILoggingConfig + * * @public */ export const DataAPILoggingDefaults: NormalizedLoggingConfig[] = [{