Client using support + minor typing bug fix (#31)

* Fixed export bug + added using support

* Fixed a couple now-broken tests

* made cursor not disposable; improved clients disposal

Author: toptobes

etc/astra-db-ts.api.md

@@ -100,10 +100,14 @@ export type ArrayUpdate<Schema> = {
 
 // @public
 export class AstraAdmin {
-    // Warning: (ae-forgotten-export) The symbol "AdminOptions" needs to be exported by the entry point index.d.ts
+    // Warning: (ae-forgotten-export) The symbol "InternalRootClientOpts" needs to be exported by the entry point index.d.ts
     //
     // @internal
-    constructor(options: AdminOptions);
+    constructor(options: InternalRootClientOpts & {
+        adminOptions: {
+            adminToken: string;
+        };
+    });
     createDatabase(config: DatabaseConfig, options?: CreateDatabaseOptions): Promise<AstraDbAdmin>;
     db(endpoint: string, options?: DbSpawnOptions): Db;
     db(id: string, region: string, options?: DbSpawnOptions): Db;
@@ -115,8 +119,6 @@ export class AstraAdmin {
 
 // @public
 export class AstraDbAdmin extends DbAdmin {
-    // Warning: (ae-forgotten-export) The symbol "InternalRootClientOpts" needs to be exported by the entry point index.d.ts
-    //
     // @internal
     constructor(_db: Db, options: InternalRootClientOpts);
     createNamespace(namespace: string, options?: AdminBlockingOptions): Promise<void>;
@@ -324,6 +326,7 @@ export class CursorIsStartedError extends DataAPIError {
 
 // @public
 export class DataAPIClient extends DataAPIClientEventEmitterBase {
+    [Symbol.asyncDispose]: () => Promise<void>;
     constructor(token: string, options?: DataAPIClientOptions | null);
     admin(options?: AdminSpawnOptions): AstraAdmin;
     close(): Promise<void>;
@@ -628,7 +631,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
     constructor(namespace: string, httpClient: DataAPIHttpClient, filter: Filter<SomeDoc>, options?: FindOptions);
     bufferedCount(): number;
     clone(): FindCursor<TRaw, TRaw>;
-    close(): Promise<void>;
+    close(): void;
     get closed(): boolean;
     filter(filter: Filter<TRaw>): FindCursor<T, TRaw>;
     // @deprecated

src/api/data-api-http-client.ts

@@ -23,7 +23,7 @@ import {
   HttpMethods,
   RawDataAPIResponse,
 } from '@/src/api';
-import { DataAPIResponseError, DataAPITimeoutError, ObjectId, UUID } from '@/src/data-api';
+import { DataAPIResponseError, DataAPITimeoutError, ObjectId, UUID, WithNamespace } from '@/src/data-api';
 import { MkTimeoutError, TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
 import { CommandFailedEvent, CommandStartedEvent, CommandSucceededEvent } from '@/src/data-api/events';
 import { CollectionNotFoundError, DataAPIHttpError, mkRespErrorFromResponse } from '@/src/data-api/errors';
@@ -39,24 +39,20 @@ export interface DataAPIRequestInfo {
   timeoutManager: TimeoutManager;
 }
 
-type ExecuteCommandOptions = TimeoutOptions & {
+type ExecuteCommandOptions = {
   collection?: string;
   namespace?: string;
 }
 
-type DataAPIHttpClientOptions = HTTPClientOptions & {
-  namespace: string;
-}
-
 /**
  * @internal
  */
 export class DataAPIHttpClient extends HttpClient {
   public collection?: string;
   public namespace?: string;
-  readonly #props: DataAPIHttpClientOptions;
+  readonly #props: HTTPClientOptions & WithNamespace;
 
-  constructor(props: DataAPIHttpClientOptions) {
+  constructor(props: HTTPClientOptions & WithNamespace) {
     super({
       ...props,
       mkAuthHeader: (token) => ({ [DEFAULT_DATA_API_AUTH_HEADER]: token }),
@@ -80,7 +76,7 @@ export class DataAPIHttpClient extends HttpClient {
     return mkTimeoutManager(timeoutMs);
   }
 
-  public async executeCommand(command: Record<string, any>, options: ExecuteCommandOptions | undefined) {
+  public async executeCommand(command: Record<string, any>, options: TimeoutOptions & ExecuteCommandOptions | undefined) {
     const timeoutManager = options?.timeoutManager ?? mkTimeoutManager(options?.maxTimeMS);
 
     return await this._requestDataAPI({

src/client/data-api-client.ts

@@ -139,6 +139,10 @@ export class DataAPIClient extends DataAPIClientEventEmitterBase {
       },
       emitter: this,
     };
+
+    if (Symbol.asyncDispose) {
+      this[Symbol.asyncDispose] = this.close;
+    }
   }
 
   /**
@@ -266,6 +270,33 @@ export class DataAPIClient extends DataAPIClientEventEmitterBase {
     await this.#options.fetchCtx.preferred.disconnectAll();
     await this.#options.fetchCtx.http1.disconnectAll();
   }
+
+  /**
+   * Allows for the `await using` syntax (if your typescript version \>= 5.2) to automatically close the client when
+   * it's out of scope.
+   *
+   * Equivalent to wrapping the client usage in a `try`/`finally` block and calling `client.close()` in the `finally`
+   * block.
+   *
+   * @example
+   * ```typescript
+   * async function main() {
+   *   // Will unconditionally close the client when the function exits
+   *   await using client = new DataAPIClient('*TOKEN*');
+   *
+   *   // Using the client as normal
+   *   const db = client.db('*ENDPOINT*');
+   *   console.log(await db.listCollections());
+   *
+   *   // Or pass it to another function to run your app
+   *   app(client);
+   * }
+   * main();
+   * ```
+   *
+   * *This will only be defined if the `Symbol.asyncDispose` symbol is actually defined.*
+   */
+  public [Symbol.asyncDispose]!: () => Promise<void>;
 }
 
 function validateRootOpts(opts: DataAPIClientOptions | undefined | null) {

src/data-api/cursor.ts

@@ -106,7 +106,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The namespace of the collection that's being iterated over.
    */
-  get namespace(): string {
+  public get namespace(): string {
     return this._namespace;
   }
 
@@ -115,7 +115,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns Whether or not the cursor is closed.
    */
-  get closed(): boolean {
+  public get closed(): boolean {
     return this._state === CursorStatus.Closed;
   }
 
@@ -124,7 +124,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The number of documents in the buffer.
    */
-  bufferedCount(): number {
+  public bufferedCount(): number {
     return this._buffer.length;
   }
 
@@ -140,7 +140,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  filter(filter: Filter<TRaw>): FindCursor<T, TRaw> {
+  public filter(filter: Filter<TRaw>): FindCursor<T, TRaw> {
     this._assertUninitialized();
     this._filter = filter as any;
     return this;
@@ -158,7 +158,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  sort(sort: Sort): FindCursor<T, TRaw> {
+  public sort(sort: Sort): FindCursor<T, TRaw> {
     this._assertUninitialized();
     this._options.sort = normalizeSort(sort);
     return this;
@@ -175,7 +175,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  limit(limit: number): FindCursor<T, TRaw> {
+  public limit(limit: number): FindCursor<T, TRaw> {
     this._assertUninitialized();
     this._options.limit = limit || Infinity;
     return this;
@@ -190,7 +190,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  skip(skip: number): FindCursor<T, TRaw> {
+  public skip(skip: number): FindCursor<T, TRaw> {
     this._assertUninitialized();
     this._options.skip = skip;
     return this;
@@ -232,7 +232,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  project<R = any, RRaw extends SomeDoc = SomeDoc>(projection: Projection): FindCursor<R, RRaw> {
+  public project<R = any, RRaw extends SomeDoc = SomeDoc>(projection: Projection): FindCursor<R, RRaw> {
     this._assertUninitialized();
     this._options.projection = projection;
     return this as any;
@@ -247,7 +247,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  includeSimilarity(includeSimilarity: boolean = true): FindCursor<T, TRaw> {
+  public includeSimilarity(includeSimilarity: boolean = true): FindCursor<T, TRaw> {
     this._assertUninitialized();
     this._options.includeSimilarity = includeSimilarity;
     return this;
@@ -265,7 +265,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The cursor.
    */
-  map<R>(mapping: (doc: T) => R): FindCursor<R, TRaw> {
+  public map<R>(mapping: (doc: T) => R): FindCursor<R, TRaw> {
     this._assertUninitialized();
 
     if (this._mapping) {
@@ -291,7 +291,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns A behavioral clone of this cursor.
    */
-  clone(): FindCursor<TRaw, TRaw> {
+  public clone(): FindCursor<TRaw, TRaw> {
     return new FindCursor<TRaw, TRaw>(this._namespace, this._httpClient, this._filter, this._options);
   }
 
@@ -304,7 +304,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The documents read from the buffer.
    */
-  readBufferedDocuments(max?: number): TRaw[] {
+  public readBufferedDocuments(max?: number): TRaw[] {
     const toRead = Math.min(max ?? this._buffer.length, this._buffer.length);
     return this._buffer.splice(0, toRead);
   }
@@ -314,7 +314,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    * cursor will remain, but iteration will start from the beginning, sending new queries to the server, even if the
    * resultant data was already fetched by this cursor.
    */
-  rewind(): void {
+  public rewind(): void {
     this._buffer.length = 0;
     this._nextPageState = undefined;
     this._state = CursorStatus.Uninitialized;
@@ -327,7 +327,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns The next document, or `null` if there are no more documents.
    */
-  async next(): Promise<T | null> {
+  public async next(): Promise<T | null> {
     return this._next(false);
   }
 
@@ -338,7 +338,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns Whether or not there is a next document.
    */
-  async hasNext(): Promise<boolean> {
+  public async hasNext(): Promise<boolean> {
     if (this._buffer.length > 0) {
       return true;
     }
@@ -370,7 +370,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    * }
    * ```
    */
-  async *[Symbol.asyncIterator](): AsyncGenerator<T, void, void> {
+  public async *[Symbol.asyncIterator](): AsyncGenerator<T, void, void> {
     try {
       while (true) {
         const doc = await this.next();
@@ -382,7 +382,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
         yield doc;
       }
     } finally {
-      await this.close();
+      this.close();
     }
   }
 
@@ -404,7 +404,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @deprecated - Prefer the `for await (const doc of cursor) { ... }` syntax instead.
    */
-  async forEach(consumer: (doc: T) => boolean | void): Promise<void> {
+  public async forEach(consumer: (doc: T) => boolean | void): Promise<void> {
     for await (const doc of this) {
       if (consumer(doc) === false) {
         break;
@@ -423,7 +423,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @returns An array of all documents in the cursor.
    */
-  async toArray(): Promise<T[]> {
+  public async toArray(): Promise<T[]> {
     const docs: T[] = [];
     for await (const doc of this) {
       docs.push(doc);
@@ -434,8 +434,9 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
   /**
    * Closes the cursor. The cursor will be unusable after this method is called, or until {@link FindCursor.rewind} is called.
    */
-  async close(): Promise<void> {
+  public close(): void {
     this._state = CursorStatus.Closed;
+    this._buffer = [];
   }
 
   private _assertUninitialized(): void {
@@ -460,7 +461,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
             ? this._mapping(doc)
             : doc;
         } catch (err) {
-          await this.close();
+          this.close();
           throw err;
         }
       }
@@ -472,7 +473,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
       try {
         await this._getMore();
       } catch (err) {
-        await this.close();
+        this.close();
         throw err;
       }
     } while (this._buffer.length !== 0);

src/data-api/types/utils.ts

@@ -22,7 +22,7 @@ import type { SomeId } from '@/src/data-api/types';
  * IsNum<string | number> === true
  * ```
  *
- * @internal
+ * @public
  */
 export type IsNum<T> = number extends T ? true : bigint extends T ? true : false
 
@@ -34,14 +34,14 @@ export type IsNum<T> = number extends T ? true : bigint extends T ? true : false
  * IsDate<string | Date> === boolean
  * ```
  *
- * @internal
+ * @public
  */
 export type IsDate<T> = IsAny<T> extends true ? true : T extends Date | { $date: number } ? true : false
 
 /**
  * Checks if a type is any
  *
- * @internal
+ * @public
  */
 export type IsAny<T> = true extends false & T ? true : false
 

src/devops/astra-admin.ts

@@ -12,8 +12,6 @@ import { AdminSpawnOptions, DbSpawnOptions, InternalRootClientOpts } from '@/src
 import { validateOption } from '@/src/data-api/utils';
 import { mkDb } from '@/src/data-api/db';
 
-type AdminOptions = InternalRootClientOpts & { adminOptions: { adminToken: string } };
-
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting databases.
  *
@@ -50,7 +48,7 @@ export class AstraAdmin {
    *
    * @internal
    */
-  constructor(options: AdminOptions) {
+  constructor(options: InternalRootClientOpts & { adminOptions: { adminToken: string } }) {
     const adminOpts = options.adminOptions ?? {};
 
     this.#defaultOpts = options;