Admin class overhauls (#79)

* make DataAPIDbAdmin keyspace options no longer extend AdminBlockingOptions

* refactor raw db info into more workable objects

* more unified naming convention of admin interfaces

* bit of name tweaking

* some admin info itnerface tweaking

* light, temp documentation

Author: toptobes

etc/astra-db-ts.api.md

@@ -14,24 +14,26 @@
 // noinspection ExceptionCaughtLocallyJS
 
 import {
-  AdminBlockingOptions,
   AdminSpawnOptions,
-  CreateDatabaseOptions,
-  DatabaseConfig,
-  FullDatabaseInfo,
-  ListDatabasesOptions,
+  AstraAdminBlockingOptions,
+  AstraDatabaseConfig,
+  CreateAstraDatabaseOptions,
+  ListAstraDatabasesOptions,
 } from '@/src/administration/types';
 import { AstraDbAdmin } from '@/src/administration/astra-db-admin';
 import { Db } from '@/src/db/db';
+import { buildAstraDatabaseAdminInfo } from '@/src/administration/utils';
 import { DEFAULT_DEVOPS_API_ENDPOINTS, DEFAULT_KEYSPACE, HttpMethods } from '@/src/lib/api/constants';
 import { DevOpsAPIHttpClient } from '@/src/lib/api/clients/devops-api-http-client';
 import { TokenProvider, WithTimeout } from '@/src/lib';
+import { AstraDbAdminInfo } from '@/src/administration/types/admin/database-info';
 import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { InternalRootClientOpts } from '@/src/client/types/internal';
 import { buildAstraEndpoint } from '@/src/lib/utils';
 import { Logger } from '@/src/lib/logging/logger';
 import { DbSpawnOptions } from '@/src/client';
 import { $CustomInspect } from '@/src/lib/constants';
+import { SomeDoc } from '@/src/documents';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting databases.
@@ -62,6 +64,7 @@ import { $CustomInspect } from '@/src/lib/constants';
 export class AstraAdmin {
   readonly #defaultOpts: InternalRootClientOpts;
   readonly #httpClient: DevOpsAPIHttpClient;
+  readonly #environment: 'dev' | 'test' | 'prod';
 
   /**
    * Use {@link DataAPIClient.admin} to obtain an instance of this class.
@@ -80,16 +83,19 @@ export class AstraAdmin {
         adminToken: token,
         logging: Logger.advanceConfig(rootOpts.adminOptions.logging, adminOpts?.logging),
         additionalHeaders: { ...rootOpts.adminOptions.additionalHeaders, ...adminOpts?.additionalHeaders },
+        astraEnv: adminOpts?.astraEnv ?? rootOpts.adminOptions.astraEnv,
       },
       dbOptions: {
         ...rootOpts.dbOptions,
         token: TokenProvider.parseToken([rootOpts.dbOptions.token, token], 'admin token'),
       },
     };
 
+    this.#environment = this.#defaultOpts.adminOptions.astraEnv ?? 'prod';
+
     this.#httpClient = new DevOpsAPIHttpClient({
-      baseUrl: this.#defaultOpts.adminOptions.endpointUrl || DEFAULT_DEVOPS_API_ENDPOINTS.prod,
       logging: this.#defaultOpts.adminOptions.logging,
+      baseUrl: this.#defaultOpts.adminOptions.endpointUrl ?? DEFAULT_DEVOPS_API_ENDPOINTS[this.#environment],
       emitter: rootOpts.emitter,
       fetchCtx: rootOpts.fetchCtx,
       userAgent: rootOpts.userAgent,
@@ -262,8 +268,7 @@ export class AstraAdmin {
 
   public dbAdmin(endpointOrId: string, regionOrOptions?: string | DbSpawnOptions, maybeOptions?: DbSpawnOptions): AstraDbAdmin {
     /* @ts-expect-error - calls internal representation of method */
-    return this.db(endpointOrId, regionOrOptions, maybeOptions)
-      .admin(this.#defaultOpts.adminOptions);
+    return this.db(endpointOrId, regionOrOptions, maybeOptions).admin(this.#defaultOpts.adminOptions);
   }
 
   /**
@@ -278,13 +283,13 @@ export class AstraAdmin {
    *
    * @returns A promise that resolves to the complete database information.
    */
-  public async dbInfo(id: string, options?: WithTimeout): Promise<FullDatabaseInfo> {
+  public async dbInfo(id: string, options?: WithTimeout): Promise<AstraDbAdminInfo> {
     const resp = await this.#httpClient.request({
       method: HttpMethods.Get,
       path: `/databases/${id}`,
     }, options);
 
-    return resp.data as FullDatabaseInfo;
+    return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
   }
 
   /**
@@ -297,7 +302,7 @@ export class AstraAdmin {
    * You can also filter by the database status using the `include` option, and by the database provider using the
    * `provider` option.
    *
-   * See {@link ListDatabasesOptions} for complete information about the options available for this operation.
+   * See {@link ListAstraDatabasesOptions} for complete information about the options available for this operation.
    *
    * @example
    * ```typescript
@@ -313,23 +318,23 @@ export class AstraAdmin {
    * @param options - The options to filter the databases by.
    * @returns A list of the complete information for all the databases matching the given filter.
    */
-  public async listDatabases(options?: ListDatabasesOptions): Promise<FullDatabaseInfo[]> {
+  public async listDatabases(options?: ListAstraDatabasesOptions): Promise<AstraDbAdminInfo[]> {
     const params = {} as Record<string, string>;
 
     if (typeof options?.include === 'string') {
-      (params['include'] = options.include);
+      params['include'] = options.include;
     }
 
     if (typeof options?.provider === 'string') {
-      (params['provider'] = options.provider);
+      params['provider'] = options.provider;
     }
 
     if (typeof options?.limit === 'number') {
-      (params['limit'] = String(options.skip));
+      params['limit'] = String(options.skip);
     }
 
     if (typeof options?.skip === 'number') {
-      (params['starting_after'] = String(options.skip));
+      params['starting_after'] = String(options.skip);
     }
 
     const resp = await this.#httpClient.request({
@@ -338,13 +343,13 @@ export class AstraAdmin {
       params: params,
     }, options);
 
-    return resp.data as FullDatabaseInfo[];
+    return resp.data!.map((d: SomeDoc) => buildAstraDatabaseAdminInfo(d, this.#environment));
   }
 
   /**
    * Creates a new database with the given configuration.
    *
-   * **NB. this is a long-running operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a long-running operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 10 seconds. Expect it to take roughly 2 min to complete.
    *
    * Note that **the `name` field is non-unique** and thus creating a database, even with the same options, is **not
@@ -354,7 +359,7 @@ export class AstraAdmin {
    * will override any default options set when creating the {@link DataAPIClient} through a deep merge (i.e. unset
    * properties in the options object will just default to the default options).
    *
-   * See {@link CreateDatabaseOptions} for complete information about the options available for this operation.
+   * See {@link CreateAstraDatabaseOptions} for complete information about the options available for this operation.
    *
    * @example
    * ```typescript
@@ -393,7 +398,7 @@ export class AstraAdmin {
    *
    * @returns The AstraDbAdmin instance for the newly created database.
    */
-  public async createDatabase(config: DatabaseConfig, options?: CreateDatabaseOptions): Promise<AstraDbAdmin> {
+  public async createDatabase(config: AstraDatabaseConfig, options?: CreateAstraDatabaseOptions): Promise<AstraDbAdmin> {
     const definition = {
       capacityUnits: 1,
       tier: 'serverless',
@@ -422,7 +427,7 @@ export class AstraAdmin {
   /**
    * Terminates a database by ID or by a given {@link Db} instance.
    *
-   * **NB. this is a long-running operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a long-running operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 10 seconds. Expect it to take roughly 6-7 min to complete.
    *
    * The database info will still be accessible by ID, or by using the {@link AstraAdmin.listDatabases} method with the filter
@@ -444,7 +449,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?: AdminBlockingOptions): Promise<void> {
+  public async dropDatabase(db: Db | string, options?: AstraAdminBlockingOptions): Promise<void> {
     const id = typeof db === 'string' ? db : db.id;
 
     await this.#httpClient.requestLongRunning({

src/administration/astra-admin.ts

@@ -14,14 +14,13 @@
 // noinspection ExceptionCaughtLocallyJS
 
 import {
-  AdminBlockingOptions,
   AdminSpawnOptions,
-  CreateKeyspaceOptions,
-  FullDatabaseInfo,
+  AstraAdminBlockingOptions,
+  AstraCreateKeyspaceOptions,
 } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
 import { WithTimeout } from '@/src/lib/types';
-import { extractAstraEnvironment } from '@/src/administration/utils';
+import { buildAstraDatabaseAdminInfo, extractAstraEnvironment } from '@/src/administration/utils';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
 import { DEFAULT_DEVOPS_API_ENDPOINTS, HttpMethods } from '@/src/lib/api/constants';
 import { DevOpsAPIHttpClient } from '@/src/lib/api/clients/devops-api-http-client';
@@ -30,8 +29,9 @@ import { StaticTokenProvider, TokenProvider } from '@/src/lib';
 import { isNullish } from '@/src/lib/utils';
 import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { InternalRootClientOpts } from '@/src/client/types/internal';
-import { Logger } from '@/src/lib/logging/logger';
 import { $CustomInspect } from '@/src/lib/constants';
+import { AstraDbAdminInfo } from '@/src/administration/types/admin/database-info';
+import { Logger } from '@/src/lib/logging/logger';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting keyspaces.
@@ -69,6 +69,7 @@ import { $CustomInspect } from '@/src/lib/constants';
 export class AstraDbAdmin extends DbAdmin {
   readonly #httpClient: DevOpsAPIHttpClient;
   readonly #db: Db;
+  readonly #environment: 'dev' | 'test' | 'prod';
 
   /**
    * Use {@link Db.admin} or {@link AstraAdmin.dbAdmin} to obtain an instance of this class.
@@ -86,10 +87,10 @@ export class AstraDbAdmin extends DbAdmin {
       ? dbToken
       : _adminToken;
 
-    const environment = extractAstraEnvironment(endpoint);
+    this.#environment = adminOpts?.astraEnv ?? rootOpts.adminOptions.astraEnv ?? extractAstraEnvironment(endpoint);
 
     this.#httpClient = new DevOpsAPIHttpClient({
-      baseUrl: adminOpts?.endpointUrl ?? rootOpts.adminOptions.endpointUrl ?? DEFAULT_DEVOPS_API_ENDPOINTS[environment],
+      baseUrl: DEFAULT_DEVOPS_API_ENDPOINTS[this.#environment],
       logging: Logger.advanceConfig(rootOpts.adminOptions.logging, adminOpts?.logging),
       fetchCtx: rootOpts.fetchCtx,
       emitter: rootOpts.emitter,
@@ -171,13 +172,13 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves to the complete database information.
    */
-  public async info(options?: WithTimeout): Promise<FullDatabaseInfo> {
+  public async info(options?: WithTimeout): Promise<AstraDbAdminInfo> {
     const resp = await this.#httpClient.request({
       method: HttpMethods.Get,
       path: `/databases/${this.#db.id}`,
     }, options);
 
-    return resp.data as FullDatabaseInfo;
+    return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
   }
 
   /**
@@ -197,13 +198,13 @@ export class AstraDbAdmin extends DbAdmin {
    * @returns A promise that resolves to list of all the keyspaces in the database.
    */
   public override async listKeyspaces(options?: WithTimeout): Promise<string[]> {
-    return this.info(options).then(i => [i.info.keyspace!, ...i.info.additionalKeyspaces ?? []].filter(Boolean));
+    return this.info(options).then(i => i.keyspaces);
   }
 
   /**
    * Creates a new, additional, keyspace for this database.
    *
-   * **NB. this is a "long-running" operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a "long-running" operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 1 second. Expect it to take roughly 8-10 seconds to complete.
    *
    * @example
@@ -230,7 +231,7 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async createKeyspace(keyspace: string, options?: CreateKeyspaceOptions): Promise<void> {
+  public override async createKeyspace(keyspace: string, options?: AstraCreateKeyspaceOptions): Promise<void> {
     if (options?.updateDbKeyspace) {
       this.#db.useKeyspace(keyspace);
     }
@@ -250,7 +251,7 @@ export class AstraDbAdmin extends DbAdmin {
   /**
    * Drops a keyspace from this database.
    *
-   * **NB. this is a "long-running" operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a "long-running" operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 1 second. Expect it to take roughly 8-10 seconds to complete.
    *
    * @example
@@ -278,7 +279,7 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async dropKeyspace(keyspace: string, options?: AdminBlockingOptions): Promise<void> {
+  public override async dropKeyspace(keyspace: string, options?: AstraAdminBlockingOptions): Promise<void> {
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Delete,
       path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
@@ -294,7 +295,7 @@ export class AstraDbAdmin extends DbAdmin {
   /**
    * Drops the database.
    *
-   * **NB. this is a long-running operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a long-running operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 10 seconds. Expect it to take roughly 6-7 min to complete.
    *
    * The database info will still be accessible by ID, or by using the {@link AstraAdmin.listDatabases} method with the filter
@@ -312,7 +313,7 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @remarks Use with caution. Use a surge protector. Don't say I didn't warn you.
    */
-  public async drop(options?: AdminBlockingOptions): Promise<void> {
+  public async drop(options?: AstraAdminBlockingOptions): Promise<void> {
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${this.#db.id}/terminate`,

src/administration/astra-db-admin.ts

@@ -13,7 +13,7 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { AdminBlockingOptions, AdminSpawnOptions, LocalCreateKeyspaceOptions } from '@/src/administration/types';
+import { AdminSpawnOptions, LocalCreateKeyspaceOptions } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
 import { WithTimeout } from '@/src/lib/types';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
@@ -141,7 +141,7 @@ export class DataAPIDbAdmin extends DbAdmin {
   /**
    * Creates a new, additional, keyspace for this database.
    *
-   * **NB. The operation will always wait for the operation to complete, regardless of the {@link AdminBlockingOptions}. Expect it to take roughly 8-10 seconds.**
+   * **NB. The operation will always wait for the operation to complete, regardless of the {@link AstraAdminBlockingOptions}. Expect it to take roughly 8-10 seconds.**
    *
    * @example
    * ```typescript
@@ -184,7 +184,7 @@ export class DataAPIDbAdmin extends DbAdmin {
   /**
    * Drops a keyspace from this database.
    *
-   * **NB. The operation will always wait for the operation to complete, regardless of the {@link AdminBlockingOptions}. Expect it to take roughly 8-10 seconds.**
+   * **NB. The operation will always wait for the operation to complete, regardless of the {@link AstraAdminBlockingOptions}. Expect it to take roughly 8-10 seconds.**
    *
    * @example
    * ```typescript
@@ -202,7 +202,7 @@ export class DataAPIDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async dropKeyspace(keyspace: string, options?: AdminBlockingOptions): Promise<void> {
+  public override async dropKeyspace(keyspace: string, options?: WithTimeout): Promise<void> {
     await this.#httpClient.executeCommand({ dropKeyspace: { name: keyspace } }, { maxTimeMS: options?.maxTimeMS, keyspace: null });
   }
 

src/administration/data-api-db-admin.ts

@@ -13,7 +13,6 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { AdminBlockingOptions, CreateKeyspaceOptions } from '@/src/administration/types';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
 import { WithTimeout } from '@/src/lib';
 import { Db } from '@/src/db';
@@ -85,7 +84,7 @@ export abstract class DbAdmin {
   /**
    * Creates a new, additional, keyspace for this database.
    *
-   * **NB. this is a "long-running" operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a "long-running" operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 1 second. Expect it to take roughly 8-10 seconds to complete.
    *
    * @example
@@ -112,11 +111,11 @@ export abstract class DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  abstract createKeyspace(keyspace: string, options?: CreateKeyspaceOptions): Promise<void>;
+  abstract createKeyspace(keyspace: string, options?: WithTimeout): Promise<void>;
   /**
    * Drops a keyspace from this database.
    *
-   * **NB. this is a "long-running" operation. See {@link AdminBlockingOptions} about such blocking operations.** The
+   * **NB. this is a "long-running" operation. See {@link AstraAdminBlockingOptions} about such blocking operations.** The
    * default polling interval is 1 second. Expect it to take roughly 8-10 seconds to complete.
    *
    * @example
@@ -144,5 +143,5 @@ export abstract class DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  abstract dropKeyspace(keyspace: string, options?: AdminBlockingOptions): Promise<void>;
+  abstract dropKeyspace(keyspace: string, options?: WithTimeout): Promise<void>;
 }