Various 2.0 cleanups/tweaks (#83)

* more intuitive naming for events/logging stuff

* formatting + timestamps for log messages

* dropIndex ifExists

* sourceModel

* createindex options resturcuting

* split filter & update types

* remove cql from datatypes names

* timeout for cursor.toArray() & coll.distinct()

* added class names for admin event name sourcse

* remove "spawn" from spawn type names

Author: toptobes

etc/astra-db-ts.api.md

@@ -17,7 +17,7 @@ sh scripts/build.sh -light || exit 2
 while [ $# -gt 0 ]; do
   case "$1" in
     "-local")
-      export CLIENT_DB_ENVIRONMENT='dse'
+      export CLIENT_DB_ENVIRONMENT='hcd'
       export CLIENT_DB_TOKEN='Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh'
       export CLIENT_DB_URL='http://localhost:8181'
       ;;

scripts/repl.sh

@@ -29,7 +29,7 @@ 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 { AdminSpawnOptions, DbSpawnOptions } from '@/src/client';
+import { AdminOptions, DbOptions } from '@/src/client';
 import { $CustomInspect } from '@/src/lib/constants';
 import { SomeDoc } from '@/src/documents';
 import { Timeouts } from '@/src/lib/api/timeouts';
@@ -71,7 +71,7 @@ export class AstraAdmin {
    *
    * @internal
    */
-  constructor(rootOpts: InternalRootClientOpts, rawAdminOpts?: AdminSpawnOptions) {
+  constructor(rootOpts: InternalRootClientOpts, rawAdminOpts?: AdminOptions) {
     const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
 
     const token = TokenProvider.parseToken([adminOpts?.adminToken, rootOpts.adminOptions.adminToken], 'admin token');
@@ -142,7 +142,7 @@ export class AstraAdmin {
    *
    * @returns A new {@link Db} instance.
    */
-  public db(endpoint: string, options?: DbSpawnOptions): Db;
+  public db(endpoint: string, options?: DbOptions): Db;
 
   /**
    * Spawns a new {@link Db} instance using a direct endpoint and given options.
@@ -176,9 +176,9 @@ export class AstraAdmin {
    *
    * @returns A new {@link Db} instance.
    */
-  public db(id: string, region: string, options?: DbSpawnOptions): Db;
+  public db(id: string, region: string, options?: DbOptions): Db;
 
-  public db(endpointOrId: string, regionOrOptions?: string | DbSpawnOptions, maybeOptions?: DbSpawnOptions): Db {
+  public db(endpointOrId: string, regionOrOptions?: string | DbOptions, maybeOptions?: DbOptions): Db {
     const dbOpts = (typeof regionOrOptions === 'string')
       ? maybeOptions
       : regionOrOptions;
@@ -229,7 +229,7 @@ export class AstraAdmin {
    *
    * @returns A new {@link Db} instance.
    */
-  public dbAdmin(endpoint: string, options?: DbSpawnOptions): AstraDbAdmin;
+  public dbAdmin(endpoint: string, options?: DbOptions): AstraDbAdmin;
 
   /**
    * Spawns a new {@link Db} instance using a direct endpoint and given options.
@@ -266,9 +266,9 @@ export class AstraAdmin {
    *
    * @returns A new {@link Db} instance.
    */
-  public dbAdmin(id: string, region: string, options?: DbSpawnOptions): AstraDbAdmin;
+  public dbAdmin(id: string, region: string, options?: DbOptions): AstraDbAdmin;
 
-  public dbAdmin(endpointOrId: string, regionOrOptions?: string | DbSpawnOptions, maybeOptions?: DbSpawnOptions): AstraDbAdmin {
+  public dbAdmin(endpointOrId: string, regionOrOptions?: string | DbOptions, maybeOptions?: DbOptions): AstraDbAdmin {
     /* @ts-expect-error - calls internal representation of method */
     return this.db(endpointOrId, regionOrOptions, maybeOptions).admin(this.#defaultOpts.adminOptions);
   }
@@ -291,6 +291,7 @@ export class AstraAdmin {
     const resp = await this.#httpClient.request({
       method: HttpMethods.Get,
       path: `/databases/${id}`,
+      methodName: 'admin.dbInfo',
     }, tm);
 
     return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);
@@ -347,6 +348,7 @@ export class AstraAdmin {
       method: HttpMethods.Get,
       path: `/databases`,
       params: params,
+      methodName: 'admin.listDatabases',
     }, tm);
 
     return resp.data!.map((d: SomeDoc) => buildAstraDatabaseAdminInfo(d, this.#environment));
@@ -419,6 +421,7 @@ export class AstraAdmin {
       method: HttpMethods.Post,
       path: '/databases',
       data: definition,
+      methodName: 'admin.createDatabase',
     }, {
       id: (resp) => resp.headers.location,
       target: 'ACTIVE',
@@ -466,6 +469,7 @@ export class AstraAdmin {
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${id}/terminate`,
+      methodName: 'admin.dropDatabase',
     }, {
       id: id,
       target: 'TERMINATED',

src/administration/astra-admin.ts

@@ -32,7 +32,8 @@ import { $CustomInspect } from '@/src/lib/constants';
 import { AstraDbAdminInfo } from '@/src/administration/types/admin/database-info';
 import { Logger } from '@/src/lib/logging/logger';
 import { TimeoutManager, Timeouts } from '@/src/lib/api/timeouts';
-import { AdminSpawnOptions } from '@/src/client';
+import { AdminOptions } from '@/src/client';
+import { DataAPIHttpClient } from '@/src/lib/api/clients';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting keyspaces.
@@ -69,6 +70,7 @@ import { AdminSpawnOptions } from '@/src/client';
  */
 export class AstraDbAdmin extends DbAdmin {
   readonly #httpClient: DevOpsAPIHttpClient;
+  readonly #dataApiHttpClient: DataAPIHttpClient<'admin'>;
   readonly #db: Db;
   readonly #environment: 'dev' | 'test' | 'prod';
 
@@ -77,7 +79,7 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @internal
    */
-  constructor(db: Db, rootOpts: InternalRootClientOpts, rawAdminOpts: AdminSpawnOptions | undefined, dbToken: TokenProvider | undefined, endpoint: string) {
+  constructor(db: Db, rootOpts: InternalRootClientOpts, rawAdminOpts: AdminOptions | undefined, dbToken: TokenProvider | undefined, endpoint: string) {
     super();
 
     const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
@@ -101,6 +103,7 @@ export class AstraDbAdmin extends DbAdmin {
       timeoutDefaults: Timeouts.merge(rootOpts.adminOptions.timeoutDefaults, adminOpts?.timeoutDefaults),
     });
 
+    this.#dataApiHttpClient = db._httpClient.forDbAdmin(adminOpts);
     this.#db = db;
 
     Object.defineProperty(this, $CustomInspect, {
@@ -155,8 +158,9 @@ export class AstraDbAdmin extends DbAdmin {
    * @returns The available embedding providers.
    */
   public override async findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult> {
-    const resp = await this.#db._httpClient.executeCommand({ findEmbeddingProviders: {} }, {
+    const resp = await this.#dataApiHttpClient.executeCommand({ findEmbeddingProviders: {} }, {
       timeoutManager: this.#httpClient.tm.single('databaseAdminTimeoutMs', options),
+      methodName: 'dbAdmin.findEmbeddingProviders',
       keyspace: null,
     });
     return resp.status as FindEmbeddingProvidersResult;
@@ -179,7 +183,7 @@ export class AstraDbAdmin extends DbAdmin {
    */
   public async info(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbAdminInfo> {
     const tm = this.#httpClient.tm.single('databaseAdminTimeoutMs', options);
-    return this.#info(tm);
+    return this.#info('dbAdmin.info', tm);
   }
 
   /**
@@ -200,7 +204,7 @@ export class AstraDbAdmin extends DbAdmin {
    */
   public override async listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]> {
     const tm = this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options);
-    return this.#info(tm).then(i => i.keyspaces);
+    return this.#info('dbAdmin.listKeyspaces', tm).then(i => i.keyspaces);
   }
 
   /**
@@ -243,6 +247,7 @@ export class AstraDbAdmin extends DbAdmin {
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
+      methodName: 'dmAdmin.createKeyspace',
     }, {
       id: this.#db.id,
       target: 'ACTIVE',
@@ -290,6 +295,7 @@ export class AstraDbAdmin extends DbAdmin {
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Delete,
       path: `/databases/${this.#db.id}/keyspaces/${keyspace}`,
+      methodName: 'dbAdmin.dropKeyspace',
     }, {
       id: this.#db.id,
       target: 'ACTIVE',
@@ -327,6 +333,7 @@ export class AstraDbAdmin extends DbAdmin {
     await this.#httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${this.#db.id}/terminate`,
+      methodName: 'dbAdmin.drop',
     }, {
       id: this.#db.id,
       target: 'TERMINATED',
@@ -341,10 +348,11 @@ export class AstraDbAdmin extends DbAdmin {
     return this.#httpClient;
   }
 
-  async #info(tm: TimeoutManager): Promise<AstraDbAdminInfo> {
+  async #info(methodName: string, tm: TimeoutManager): Promise<AstraDbAdminInfo> {
     const resp = await this.#httpClient.request({
       method: HttpMethods.Get,
       path: `/databases/${this.#db.id}`,
+      methodName,
     }, tm);
 
     return buildAstraDatabaseAdminInfo(resp.data!, this.#environment);

src/administration/astra-db-admin.ts

@@ -13,15 +13,15 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { LocalCreateKeyspaceOptions } from '@/src/administration/types';
+import { DataAPICreateKeyspaceOptions } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
 import type { WithTimeout } from '@/src/lib';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
 import { DataAPIHttpClient } from '@/src/lib/api/clients/data-api-http-client';
 import { Db } from '@/src/db';
 import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { $CustomInspect } from '@/src/lib/constants';
-import { AdminSpawnOptions } from '@/src/client';
+import { AdminOptions } from '@/src/client';
 
 /**
  * An administrative class for managing non-Astra databases, including creating, listing, and deleting keyspaces.
@@ -57,15 +57,15 @@ import { AdminSpawnOptions } from '@/src/client';
  * @public
  */
 export class DataAPIDbAdmin extends DbAdmin {
-  readonly #httpClient: DataAPIHttpClient;
+  readonly #httpClient: DataAPIHttpClient<'admin'>;
   readonly #db: Db;
 
   /**
    * Use {@link Db.admin} to obtain an instance of this class.
    *
    * @internal
    */
-  constructor(db: Db, httpClient: DataAPIHttpClient, rawAdminOpts?: AdminSpawnOptions) {
+  constructor(db: Db, httpClient: DataAPIHttpClient, rawAdminOpts?: AdminOptions) {
     super();
     const adminOpts = parseAdminSpawnOpts(rawAdminOpts, 'options');
     this.#httpClient = httpClient.forDbAdmin(adminOpts);
@@ -116,6 +116,7 @@ export class DataAPIDbAdmin extends DbAdmin {
   public override async findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult> {
     const resp = await this.#httpClient.executeCommand({ findEmbeddingProviders: {} }, {
       timeoutManager: this.#httpClient.tm.single('databaseAdminTimeoutMs', options),
+      methodName: 'dbAdmin.findEmbeddingProviders',
       keyspace: null,
     });
     return resp.status as FindEmbeddingProvidersResult;
@@ -140,6 +141,7 @@ export class DataAPIDbAdmin extends DbAdmin {
   public override async listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]> {
     const resp = await this.#httpClient.executeCommand({ findKeyspaces: {} }, {
       timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
+      methodName: 'dbAdmin.listKeyspaces',
       keyspace: null,
     });
     return resp.status!.keyspaces;
@@ -175,7 +177,7 @@ export class DataAPIDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async createKeyspace(keyspace: string, options?: LocalCreateKeyspaceOptions): Promise<void> {
+  public override async createKeyspace(keyspace: string, options?: DataAPICreateKeyspaceOptions): Promise<void> {
     if (options?.updateDbKeyspace) {
       this.#db.useKeyspace(keyspace);
     }
@@ -187,6 +189,7 @@ export class DataAPIDbAdmin extends DbAdmin {
 
     await this.#httpClient.executeCommand({ createKeyspace: { name: keyspace, options: { replication } } }, {
       timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
+      methodName: 'dbAdmin.createKeyspace',
       keyspace: null,
     });
   }
@@ -215,6 +218,7 @@ export class DataAPIDbAdmin extends DbAdmin {
   public override async dropKeyspace(keyspace: string, options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<void> {
     await this.#httpClient.executeCommand({ dropKeyspace: { name: keyspace } }, {
       timeoutManager: this.#httpClient.tm.single('keyspaceAdminTimeoutMs', options),
+      methodName: 'dbAdmin.dropKeyspace',
       keyspace: null,
     });
   }