added support for admin.dbInfo (#34)

Author: toptobes

etc/astra-db-ts.api.md

@@ -113,6 +113,7 @@ export class AstraAdmin {
     db(id: string, region: string, options?: DbSpawnOptions): Db;
     dbAdmin(endpoint: string, options?: DbSpawnOptions): AstraDbAdmin;
     dbAdmin(id: string, region: string, options?: DbSpawnOptions): AstraDbAdmin;
+    dbInfo(id: string, options?: WithTimeout): Promise<FullDatabaseInfo>;
     dropDatabase(db: Db | string, options?: AdminBlockingOptions): Promise<void>;
     listDatabases(options?: ListDatabasesOptions): Promise<FullDatabaseInfo[]>;
 }
@@ -187,6 +188,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
     deleteOne(filter?: Filter<Schema>, options?: DeleteOneOptions): Promise<DeleteOneResult>;
     distinct<Key extends string>(key: Key, filter?: Filter<Schema>): Promise<Flatten<(SomeDoc & ToDotNotation<FoundDoc<Schema>>)[Key]>[]>;
     drop(options?: WithTimeout): Promise<boolean>;
+    estimatedDocumentCount(options?: WithTimeout): Promise<number>;
     find(filter: Filter<Schema>, options?: FindOptions): FindCursor<FoundDoc<Schema>, FoundDoc<Schema>>;
     findOne(filter: Filter<Schema>, options?: FindOneOptions): Promise<FoundDoc<Schema> | null>;
     findOneAndDelete(filter: Filter<Schema>, options: FindOneAndDeleteOptions & {
@@ -345,6 +347,8 @@ export interface DataAPIClientOptions {
     adminOptions?: AdminSpawnOptions;
     caller?: Caller | Caller[];
     dbOptions?: DbSpawnOptions;
+    httpOptions?: DataAPIHttpOptions;
+    // @deprecated
     preferHttp2?: boolean;
 }
 
@@ -373,6 +377,21 @@ export interface DataAPIErrorDescriptor {
     readonly message?: string;
 }
 
+// @public
+export interface DataAPIHttp1Options {
+    keepAlive?: boolean;
+    keepAliveMS?: number;
+    maxFreeSockets?: number;
+    maxSockets?: number;
+}
+
+// @public
+export interface DataAPIHttpOptions {
+    http1?: DataAPIHttp1Options;
+    maxTimeMS?: number;
+    preferHttp2?: boolean;
+}
+
 // @public
 export class DataAPIResponseError extends DataAPIError {
     // @internal

src/client/index.ts

@@ -14,4 +14,4 @@
 // noinspection DuplicatedCode
 
 export * from './data-api-client';
-export { DbSpawnOptions, AdminSpawnOptions, DataAPIClientOptions, Caller } from './types';
+export { DbSpawnOptions, AdminSpawnOptions, DataAPIClientOptions, Caller, DataAPIHttpOptions, DataAPIHttp1Options } from './types';

src/client/types.ts

@@ -85,9 +85,13 @@ export interface DataAPIClientOptions {
    */
   caller?: Caller | Caller[],
   /**
-   * **Prefer to use the {@link httpOptions} property instead.**
+   * Whether to prefer HTTP/2 for requests to the Data API; if set to `false`, HTTP/1.1 will be used instead.
+   *
+   * **Prefer to use the {@link DataAPIClientOptions.httpOptions} property instead.**
    *
-   * @deprecated
+   * The two are functionally equivalent; this is provided for backwards compatibility.
+   *
+   * @deprecated Use the {@link DataAPIClientOptions.httpOptions} property instead.
    *
    * @see DataAPIHttpOptions
    */
@@ -96,6 +100,8 @@ export interface DataAPIClientOptions {
 
 /**
  * The options available for the {@link DataAPIClient} related to making HTTP requests.
+ *
+ * @public
  */
 export interface DataAPIHttpOptions {
   /**
@@ -127,6 +133,8 @@ export interface DataAPIHttpOptions {
 
 /**
  * The options available for the {@link DataAPIClient} related to making HTTP/1.1 requests.
+ *
+ * @public
  */
 export interface DataAPIHttp1Options {
   /**

src/data-api/db.ts

@@ -509,7 +509,7 @@ export function validateDbOpts(opts: DbSpawnOptions | undefined) {
     return;
   }
 
-  validateOption<string>('namespace option', opts.namespace, 'string', (namespace) => {
+  validateOption('namespace option', opts.namespace, 'string', (namespace) => {
     if (!namespace.match(/^\w{1,48}$/)) {
       throw new Error('Invalid namespace option; expected a string of 1-48 alphanumeric characters');
     }

src/devops/astra-admin.ts

@@ -11,6 +11,7 @@ import { AstraDbAdmin } from '@/src/devops/astra-db-admin';
 import { AdminSpawnOptions, DbSpawnOptions, InternalRootClientOpts } from '@/src/client/types';
 import { validateOption } from '@/src/data-api/utils';
 import { mkDb } from '@/src/data-api/db';
+import { WithTimeout } from '@/src/common';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting databases.
@@ -216,6 +217,27 @@ export class AstraAdmin {
     return this.db(endpointOrId, regionOrOptions, maybeOptions).admin(this.#defaultOpts.adminOptions);
   }
 
+  /**
+   * Fetches the complete information about the database, such as the database name, IDs, region, status, actions, and
+   * other metadata.
+   *
+   * @example
+   * ```typescript
+   * const info = await admin.info('<db_id>');
+   * console.log(info.info.name, info.creationTime);
+   * ```
+   *
+   * @returns A promise that resolves to the complete database information.
+   */
+  public async dbInfo(id: string, options?: WithTimeout): Promise<FullDatabaseInfo> {
+    const resp = await this._httpClient.request({
+      method: HttpMethods.Get,
+      path: `/databases/${id}`,
+    }, options);
+
+    return resp.data as FullDatabaseInfo;
+  }
+
   /**
    * Lists all databases in the current org/account, matching the optionally provided filter.
    *

src/devops/astra-db-admin.ts

@@ -101,7 +101,6 @@ export class AstraDbAdmin extends DbAdmin {
    * The method issues a request to the DevOps API each time it is invoked, without caching mechanisms;
    * this ensures up-to-date information for usages such as real-time collection validation by the application.
    *
-   *
    * @example
    * ```typescript
    * const info = await dbAdmin.info();

tests/integration/devops/lifecycle.test.ts

@@ -58,12 +58,16 @@ describe('integration.devops.lifecycle', async () => {
       }
 
       {
-        const dbInfo = await asyncDbAdmin.info();
-        assert.ok(['PENDING', 'INITIALIZING'].includes(dbInfo.status));
-        assert.strictEqual(dbInfo.info.name, 'astra-test-db');
-        assert.strictEqual(dbInfo.info.cloudProvider, 'GCP');
-        assert.strictEqual(dbInfo.info.region, 'us-east1');
-        assert.strictEqual(dbInfo.info.keyspace, 'my_namespace');
+        const dbInfo1 = await asyncDbAdmin.info();
+        assert.ok(['PENDING', 'INITIALIZING'].includes(dbInfo1.status));
+        assert.strictEqual(dbInfo1.info.name, 'astra-test-db');
+        assert.strictEqual(dbInfo1.info.cloudProvider, 'GCP');
+        assert.strictEqual(dbInfo1.info.region, 'us-east1');
+        assert.strictEqual(dbInfo1.info.keyspace, 'my_namespace');
+
+        const dbInfo2 = await admin.dbInfo(asyncDb.id);
+        assert.deepStrictEqual(dbInfo1.info, dbInfo2.info);
+        assert.ok(['PENDING', 'INITIALIZING'].includes(dbInfo2.status));
       }
 
       const monitoringAdmin = client.admin({ monitorCommands: true });