some last-minute doc updates + error management fixes

Author: toptobes

README.md

@@ -21,62 +21,70 @@ interface Idea extends VectorDoc {
 }
 
 // Connect to the db
-const client = new DataAPIClient('*TOKEN*');
-const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
+const client = new DataAPIClient('AstraCS:OengMjURbGWRjuMTBMqXWwOn:3bcbf200a056069bb00f17fa52d92d935952a1f2ac58c99596edabb1e1b3950c');
+const db = client.db('https://f1183f14-dc85-4fbf-8aae-f1ca97338bbb-us-east-1.apps.astra.datastax.com');
 
 (async () => {
-  // Creates collection, or gets it if it already exists with same options
-  const collection = await db.createCollection<Idea>('vector_5_collection', {
-    vector: {
-      dimension: 5,
-      metric: 'cosine'
-    },
-  });
-
-  // Insert many ideas into the collection
-  const ideas = [
-    {
-      idea: 'An AI quilt to help you sleep forever',
-      $vector: [0.1, 0.15, 0.3, 0.12, 0.05],
-    },
-    {
-      _id: new UUID('e7f1f3a0-7e3d-11eb-9439-0242ac130002'),
-      idea: 'Vision Vector Frame—A deep learning display that controls your mood',
-      $vector: [0.1, 0.05, 0.08, 0.3, 0.6],
-    },
-    {
-      idea: 'A smartwatch that tells you what to eat based on your mood',
-      $vector: [0.2, 0.3, 0.1, 0.4, 0.15],
-    },
-  ];
-  await collection.insertMany(ideas);
-
-  // Insert a specific idea into the collection
-  const sneakersIdea = {
-    _id: new ObjectId('507f191e810c19729de860ea'),
-    idea: 'ChatGPT-integrated sneakers that talk to you',
-    $vector: [0.45, 0.09, 0.01, 0.2, 0.11],
-  }
-  await collection.insertOne(sneakersIdea);
-
-  // Actually, let's change that idea
-  await collection.updateOne(
-    { _id: sneakersIdea._id },
-    { $set: { idea: 'Gemini-integrated sneakers that talk to you' } },
-  );
-
-  // Get similar results as desired
-  const cursor = collection.find({}, {
-    vector: [0.1, 0.15, 0.3, 0.12, 0.05],
-    includeSimilarity: true,
-    limit: 2,
-  });
-
-  for await (const doc of cursor) {
-    // Prints the following:
-    // - An AI quilt to help you sleep forever: 1
-    // - A smartwatch that tells you what to eat based on your mood: 0.85490346
-    console.log(`${doc.idea}: ${doc.$similarity}`);
+  try {
+    // Creates collection, or gets it if it already exists with same options
+    const collection = await db.createCollection<Idea>('vector_5_collection', {
+      vector: {
+        dimension: 5,
+        metric: 'cosine'
+      },
+      checkExists: false,
+    });
+
+    // Insert many ideas into the collection
+    const ideas = [
+      {
+        idea: 'An AI quilt to help you sleep forever',
+        $vector: [0.1, 0.15, 0.3, 0.12, 0.05],
+      },
+      {
+        _id: new UUID('e7f1f3a0-7e3d-11eb-9439-0242ac130002'),
+        idea: 'Vision Vector Frame—A deep learning display that controls your mood',
+        $vector: [0.1, 0.05, 0.08, 0.3, 0.6],
+      },
+      {
+        idea: 'A smartwatch that tells you what to eat based on your mood',
+        $vector: [0.2, 0.3, 0.1, 0.4, 0.15],
+      },
+    ];
+    await collection.insertMany(ideas);
+
+    // Insert a specific idea into the collection
+    const sneakersIdea = {
+      _id: new ObjectId('507f191e810c19729de860ea'),
+      idea: 'ChatGPT-integrated sneakers that talk to you',
+      $vector: [0.45, 0.09, 0.01, 0.2, 0.11],
+    }
+    await collection.insertOne(sneakersIdea);
+
+    // Actually, let's change that idea
+    await collection.updateOne(
+      { _id: sneakersIdea._id },
+      { $set: { idea: 'Gemini-integrated sneakers that talk to you' } },
+    );
+
+    // Get similar results as desired
+    const cursor = collection.find({}, {
+      vector: [0.1, 0.15, 0.3, 0.12, 0.05],
+      includeSimilarity: true,
+      limit: 2,
+    });
+
+    for await (const doc of cursor) {
+      // Prints the following:
+      // - An AI quilt to help you sleep forever: 1
+      // - A smartwatch that tells you what to eat based on your mood: 0.85490346
+      console.log(`${doc.idea}: ${doc.$similarity}`);
+    }
+
+    await collection.drop();
+  } finally {
+    // Cleans up all open http sessions
+    await client.close();
   }
 })();
 ```
@@ -176,31 +184,34 @@ Native JS `Date` objects can be used anywhere in documents to represent dates an
 Document fields stored using the `{ $date: number }` will also be returned as Date objects when read.
 
 ```typescript
-import { DataApiClient } from '@datastax/astra-db-ts';
+import { DataAPIClient } from '@datastax/astra-db-ts';
 
 // Reference an untyped collection
-const client = new DataApiClient('TOKEN');
-const db = client.db('ENDPOINT', { namespace: 'NAMESPACE' });
-const collection = db.collection('COLLECTION');
-
-// 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 },
-  },
-);
+const client = new DataAPIClient('*TOKEN*');
+const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
+const collection = db.collection('*COLLECTION*');
+
+(async () => {
+  // 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);
+})();
 
-// 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);
 ```
 
 ### Working with ObjectIds and UUIDs
@@ -285,8 +296,10 @@ client.on('commandFailed', (event) => {
 const db = client.db('*ENDPOINT*');
 const coll = db.collection('*COLLECTION*');
 
-// Should log
-// - "Running command insertOne"
-// - "Command insertOne succeeded in <time>ms"
-await coll.insertOne({ name: 'Queen' });
+(async () => {
+  // Should log
+  // - "Running command insertOne"
+  // - "Command insertOne succeeded in <time>ms"
+  await coll.insertOne({ name: 'Queen' });
+})();
 ```

etc/astra-db-ts.api.md

@@ -5,7 +5,7 @@
 ```ts
 
 import { context as context_2 } from 'fetch-h2';
-import { Headers as Headers_2 } from 'fetch-h2/dist/lib/headers';
+import { Response as Response_2 } from 'fetch-h2';
 import TypedEmitter from 'typed-emitter';
 
 // @public
@@ -57,10 +57,8 @@ export class AdminCommandStartedEvent extends AdminCommandEvent {
 
 // @public
 export class AdminCommandSucceededEvent extends AdminCommandEvent {
-    // Warning: (ae-forgotten-export) The symbol "GuaranteedAPIResponse" needs to be exported by the entry point index.d.ts
-    //
     // @internal
-    constructor(info: DevOpsAPIRequestInfo, longRunning: boolean, resp: GuaranteedAPIResponse, started: number);
+    constructor(info: DevOpsAPIRequestInfo, longRunning: boolean, data: Record<string, any> | undefined, started: number);
     readonly duration: number;
     readonly resBody?: Record<string, any>;
 }
@@ -146,6 +144,7 @@ export interface BulkWriteOrderedOptions extends WithTimeout {
 
 // @public
 export class BulkWriteResult<Schema extends SomeDoc> {
+    // @internal
     constructor(
     deletedCount?: number,
     insertedCount?: number,
@@ -217,6 +216,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
 
 // @public
 export class CollectionAlreadyExistsError extends DataAPIError {
+    // @internal
     constructor(namespace: string, collectionName: string);
     readonly collectionName: string;
     readonly namespace: string;
@@ -299,6 +299,16 @@ export abstract class CumulativeDataAPIError extends DataAPIResponseError {
     readonly partialResult: unknown;
 }
 
+// @public
+export interface CuratedAPIResponse {
+    body?: string;
+    headers: Record<string, any>;
+    httpVersion: 1 | 2;
+    status: number;
+    statusText: string;
+    url: string;
+}
+
 // @public
 export type CurrentDate<Schema> = {
     [K in keyof Schema as Schema[K] extends Date | {
@@ -361,14 +371,16 @@ export interface DataAPIErrorDescriptor {
 
 // @public
 export class DataAPIResponseError extends DataAPIError {
+    // @internal
     constructor(message: string, errorDescriptors: DataAPIErrorDescriptor[], detailedErrorDescriptors: DataAPIDetailedErrorDescriptor[]);
     readonly detailedErrorDescriptors: DataAPIDetailedErrorDescriptor[];
     readonly errorDescriptors: DataAPIErrorDescriptor[];
     readonly message: string;
 }
 
 // @public
-export class DataAPITimeout extends DataAPIError {
+export class DataAPITimeoutError extends DataAPIError {
+    // @internal
     constructor(timeout: number);
     readonly timeout: number;
 }
@@ -552,14 +564,17 @@ export interface DevOpsAPIErrorDescriptor {
 
 // @public
 export class DevOpsAPIResponseError extends DevOpsAPIError {
+    // Warning: (ae-forgotten-export) The symbol "ResponseWithBody" needs to be exported by the entry point index.d.ts
+    //
     // @internal
-    constructor(resp: GuaranteedAPIResponse);
+    constructor(resp: ResponseWithBody, data: Record<string, any> | undefined);
     readonly errors: DevOpsAPIErrorDescriptor[];
-    readonly status?: number;
+    readonly raw: CuratedAPIResponse;
+    readonly status: number;
 }
 
 // @public
-export class DevOpsAPITimeout extends DevOpsAPIError {
+export class DevOpsAPITimeoutError extends DevOpsAPIError {
     // @internal
     constructor(url: string, timeout: number);
     readonly timeout: number;
@@ -569,9 +584,9 @@ export class DevOpsAPITimeout extends DevOpsAPIError {
 // @public
 export class DevOpsUnexpectedStateError extends DevOpsAPIError {
     // @internal
-    constructor(message: string, raw?: GuaranteedAPIResponse);
+    constructor(message: string, expected: string[], data: Record<string, any> | undefined);
     readonly dbInfo?: FullDatabaseInfo;
-    readonly status?: number;
+    readonly expected: string[];
 }
 
 // @public
@@ -934,7 +949,7 @@ export type Sort = Record<string, SortDirection> | {
 };
 
 // @public
-export type SortDirection = 1 | -1;
+export type SortDirection = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
 
 // @public
 export type StrictDateUpdate<Schema extends SomeDoc, InNotation = ToDotNotation<Schema>> = ContainsDate<InNotation> extends true ? {
@@ -1023,6 +1038,7 @@ export type ToDotNotation<Schema extends SomeDoc> = Merge<_ToDotNotation<Schema,
 
 // @public
 export class TooManyDocumentsToCountError extends DataAPIError {
+    // @internal
     constructor(limit: number, hitServerLimit: boolean);
     readonly hitServerLimit: boolean;
     readonly limit: number;