Mutable DB namespaces (#60)

* mutable namespaces (no docs + testing)

* documentation for mutable namespaces

* tests for mutable namespace

Author: toptobes

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

@@ -15,12 +15,13 @@
 
 import {
   DEFAULT_DATA_API_AUTH_HEADER,
-  DEFAULT_NAMESPACE,
-  DEFAULT_TIMEOUT, HeaderProvider,
+  DEFAULT_TIMEOUT,
+  HeaderProvider,
   hrTimeMs,
   HttpClient,
   HTTPClientOptions,
   HttpMethods,
+  NamespaceRef,
   RawDataAPIResponse,
 } from '@/src/api';
 import { DataAPIResponseError, DataAPITimeoutError, ObjectId, UUID } from '@/src/data-api';
@@ -94,7 +95,7 @@ const adaptInfo4Devops = (info: DataAPIRequestInfo) => (<const>{
 });
 
 interface DataAPIHttpClientOpts extends HTTPClientOptions {
-  namespace: string | undefined,
+  namespace: NamespaceRef,
   emissionStrategy: EmissionStrategy,
   embeddingHeaders: EmbeddingHeadersProvider,
   tokenProvider: TokenProvider,
@@ -105,14 +106,14 @@ interface DataAPIHttpClientOpts extends HTTPClientOptions {
  */
 export class DataAPIHttpClient extends HttpClient {
   public collection?: string;
-  public namespace?: string;
+  public namespace?: NamespaceRef;
   public maxTimeMS: number;
   public emissionStrategy: ReturnType<EmissionStrategy>
   readonly #props: DataAPIHttpClientOpts;
 
   constructor(props: DataAPIHttpClientOpts) {
     super(props, [mkAuthHeaderProvider(props.tokenProvider), props.embeddingHeaders.getHeaders.bind(props.embeddingHeaders)]);
-    this.namespace = 'namespace' in props ? props.namespace : DEFAULT_NAMESPACE;
+    this.namespace = props.namespace;
     this.#props = props;
     this.maxTimeMS = this.fetchCtx.maxTimeMS ?? DEFAULT_TIMEOUT;
     this.emissionStrategy = props.emissionStrategy(props.emitter);
@@ -122,7 +123,7 @@ export class DataAPIHttpClient extends HttpClient {
     const clone = new DataAPIHttpClient({
       ...this.#props,
       embeddingHeaders: EmbeddingHeadersProvider.parseHeaders(opts?.embeddingApiKey),
-      namespace: namespace,
+      namespace: { ref: namespace },
     });
 
     clone.collection = collection;
@@ -171,7 +172,7 @@ export class DataAPIHttpClient extends HttpClient {
       info.collection ||= this.collection;
 
       if (info.namespace !== null) {
-        info.namespace ||= this.namespace;
+        info.namespace ||= this.namespace?.ref;
       }
 
       const keyspacePath = info.namespace ? `/${info.namespace}` : '';

src/api/clients/types.ts

@@ -16,6 +16,7 @@ import type TypedEmitter from 'typed-emitter';
 import type { DataAPICommandEvents } from '@/src/data-api';
 import type { FetchCtx, HttpMethods } from '@/src/api';
 import type { TimeoutManager } from '@/src/api/timeout-managers';
+import { Ref } from '@/src/common';
 
 /**
  * @internal
@@ -39,6 +40,11 @@ export type HeaderProvider = (() => Promise<Record<string, string>> | Record<str
  */
 export type HttpMethodStrings = typeof HttpMethods[keyof typeof HttpMethods];
 
+/**
+ * @internal
+ */
+export type NamespaceRef = Ref<string | undefined>;
+
 /**
  * @internal
  */

src/api/fetch/types.ts

@@ -13,6 +13,8 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
+import { Ref } from '@/src/common';
+
 /**
  * A simple adapter interface that allows you to define a custom http client that `astra-db-ts` may use to make requests.
  *
@@ -119,6 +121,6 @@ export interface FetcherResponseInfo {
  */
 export interface FetchCtx {
   ctx: Fetcher,
-  closed: { ref: boolean },
+  closed: Ref<boolean>,
   maxTimeMS: number | undefined,
 }

src/common/types.ts

@@ -46,3 +46,8 @@ export type nullish = null | undefined;
  * @public
  */
 export type DataAPIEnvironment = typeof DataAPIEnvironments[number];
+
+/**
+ * @internal
+ */
+export type Ref<T> = { ref: T }

src/data-api/db.ts

@@ -23,7 +23,7 @@ import {
   DataAPIHttpClient,
   DEFAULT_DATA_API_PATHS,
   DEFAULT_NAMESPACE,
-  EmissionStrategy,
+  EmissionStrategy, NamespaceRef,
   RawDataAPIResponse,
 } from '@/src/api';
 import {
@@ -84,21 +84,58 @@ export class Db {
   readonly #defaultOpts!: InternalRootClientOpts;
   readonly #token!: TokenProvider;
 
-  private readonly _httpClient!: DataAPIHttpClient;
+  private readonly _httpClient: DataAPIHttpClient;
+  private readonly _namespace: NamespaceRef;
   private readonly _id?: string;
 
+  /**
+   * Use {@link DataAPIClient.db} to obtain an instance of this class.
+   *
+   * @internal
+   */
+  constructor(endpoint: string, rootOpts: InternalRootClientOpts, dbOpts: DbSpawnOptions | nullish) {
+    this.#defaultOpts = rootOpts;
+
+    this.#token = TokenProvider.parseToken(dbOpts?.token ?? rootOpts.dbOptions.token);
+
+    const combinedDbOpts = {
+      ...rootOpts.dbOptions,
+      ...dbOpts,
+    }
+
+    this._namespace = {
+      ref: (rootOpts.environment === 'astra')
+        ? combinedDbOpts.namespace ?? DEFAULT_NAMESPACE
+        : combinedDbOpts.namespace
+    };
+
+    this._httpClient = new DataAPIHttpClient({
+      baseUrl: endpoint,
+      tokenProvider: this.#token,
+      embeddingHeaders: EmbeddingHeadersProvider.parseHeaders(null),
+      baseApiPath: combinedDbOpts.dataApiPath || DEFAULT_DATA_API_PATHS[rootOpts.environment],
+      emitter: rootOpts.emitter,
+      monitorCommands: combinedDbOpts.monitorCommands,
+      fetchCtx: rootOpts.fetchCtx,
+      namespace: this._namespace,
+      userAgent: rootOpts.userAgent,
+      emissionStrategy: EmissionStrategy.Normal,
+    });
+
+    this._id = extractDbIdFromUrl(endpoint);
+  }
+
   /**
    * The default namespace to use for all operations in this database, unless overridden in a method call.
    *
    * @example
    * ```typescript
-   *
    * // Uses 'default_keyspace' as the default namespace for all future db spawns
    * const client1 = new DataAPIClient('*TOKEN*');
    *
    * // Overrides the default namespace for all future db spawns
    * const client2 = new DataAPIClient('*TOKEN*', {
-   *   dbOptions: { namespace: 'my_namespace' }
+   *   dbOptions: { namespace: 'my_namespace' },
    * });
    *
    * // Created with 'default_keyspace' as the default namespace
@@ -118,62 +155,70 @@ export class Db {
    * });
    * ```
    */
-  public readonly namespace!: string;
-
-  /**
-   * Use {@link DataAPIClient.db} to obtain an instance of this class.
-   *
-   * @internal
-   */
-  constructor(endpoint: string, rootOpts: InternalRootClientOpts, dbOpts: DbSpawnOptions | nullish) {
-    this.#defaultOpts = rootOpts;
-
-    this.#token = TokenProvider.parseToken(dbOpts?.token ?? rootOpts.dbOptions.token);
-
-    const combinedDbOpts = {
-      ...rootOpts.dbOptions,
-      ...dbOpts,
+  public get namespace(): string {
+    if (!this._namespace.ref) {
+      throw new Error('No namespace set for DB (can\'t do db.namespace)');
     }
-
-    Object.defineProperty(this, 'namespace', {
-      value: combinedDbOpts.namespace ?? DEFAULT_NAMESPACE,
-      writable: false,
-    });
-
-    Object.defineProperty(this, '_httpClient', {
-      value: new DataAPIHttpClient({
-        baseUrl: endpoint,
-        tokenProvider: this.#token,
-        embeddingHeaders: EmbeddingHeadersProvider.parseHeaders(null),
-        baseApiPath: combinedDbOpts.dataApiPath || DEFAULT_DATA_API_PATHS[rootOpts.environment],
-        emitter: rootOpts.emitter,
-        monitorCommands: combinedDbOpts.monitorCommands,
-        fetchCtx: rootOpts.fetchCtx,
-        namespace: this.namespace,
-        userAgent: rootOpts.userAgent,
-        emissionStrategy: EmissionStrategy.Normal,
-      }),
-      enumerable: false,
-    });
-
-    Object.defineProperty(this, '_id', {
-      value: extractDbIdFromUrl(endpoint),
-      enumerable: false,
-    });
+    return this._namespace.ref;
   }
 
   /**
    * The ID of the database, if it's an Astra database. If it's not an Astra database, this will throw an error.
    *
    * @throws Error - if the database is not an Astra database.
    */
-  get id(): string {
+  public get id(): string {
     if (!this._id) {
       throw new Error('Non-Astra databases do not have an appropriate ID');
     }
     return this._id;
   }
 
+  /**
+   * Sets the default working namespace of the `Db` instance. Does not retroactively update any previous collections
+   * spawned from this `Db` to use the new namespace.
+   *
+   * @example
+   * ```typescript
+   * // Spawns a `Db` with default working namespace `my_namespace`
+   * const db = client.db('<endpoint>', { namespace: 'my_namespace' });
+   *
+   * // Gets a collection from namespace `my_namespace`
+   * const coll1 = db.collection('my_coll');
+   *
+   * // `db` now uses `my_other_namespace` as the default namespace for all operations
+   * db.useNamespace('my_other_namespace');
+   *
+   * // Gets a collection from namespace `my_other_namespace`
+   * // `coll1` still uses namespace `my_namespace`
+   * const coll2 = db.collection('my_other_coll');
+   *
+   * // Gets `my_coll` from namespace `my_namespace` again
+   * // (The default namespace is still `my_other_namespace`)
+   * const coll3 = db.collection('my_coll', { namespace: 'my_namespace' });
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // If using non-astra, this may be a common idiom:
+   * const client = new DataAPIClient({ environment: 'dse' });
+   * const db = client.db('<endpoint>', { token: '<token>' });
+   *
+   * // Will internally call `db.useNamespace('new_namespace')`
+   * await db.admin().createNamespace('new_namespace', {
+   *   updateDbNamespace: true,
+   * });
+   *
+   * // Creates collection in namespace `new_namespace` by default now
+   * const coll = db.createCollection('my_coll');
+   * ```
+   *
+   * @param namespace - The namespace to use
+   */
+  public useNamespace(namespace: string) {
+    this._namespace.ref = namespace;
+  }
+
   /**
    * Spawns a new {@link AstraDbAdmin} instance for this database, used for performing administrative operations
    * on the database, such as managing namespaces, or getting database information.

src/data-api/types/misc/spawn-db.ts

@@ -25,8 +25,13 @@ export interface DbSpawnOptions {
   /**
    * The namespace (aka keyspace) to use for the database.
    *
-   * Defaults to `'default_keyspace'`. if never provided. However, if it was provided when creating the
-   * {@link DataAPIClient}, it will default to that value instead.
+   * There are a few rules for what the default namespace will be:
+   * 1. If a namespace was provided when creating the {@link DataAPIClient}, it will default to that value.
+   * 2. If using an `astra` database, it'll default to "default_namespace".
+   * 3. Otherwise, no default will be set, and it'll be on the user to provide one when necessary.
+   *
+   * The client itself will not throw an error if an invalid namespace (or even no namespace at all) is provided—it'll
+   * let the Data API propagate the error itself.
    *
    * Every db method will use this namespace as the default namespace, but they all allow you to override it
    * in their options.

src/devops/astra-db-admin.ts

@@ -13,7 +13,7 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { AdminBlockingOptions, AdminSpawnOptions, FullDatabaseInfo } from '@/src/devops/types';
+import { AdminBlockingOptions, AdminSpawnOptions, CreateNamespaceOptions, FullDatabaseInfo } from '@/src/devops/types';
 import { DEFAULT_DEVOPS_API_ENDPOINT, DEFAULT_NAMESPACE, DevOpsAPIHttpClient, HttpMethods } from '@/src/api';
 import { Db } from '@/src/data-api';
 import { DbAdmin } from '@/src/devops/db-admin';
@@ -202,7 +202,7 @@ export class AstraDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async createNamespace(namespace: string, options?: AdminBlockingOptions): Promise<void> {
+  public override async createNamespace(namespace: string, options?: CreateNamespaceOptions): Promise<void> {
     await this._httpClient.requestLongRunning({
       method: HttpMethods.Post,
       path: `/databases/${this._db.id}/keyspaces/${namespace}`,
@@ -213,6 +213,10 @@ export class AstraDbAdmin extends DbAdmin {
       defaultPollInterval: 1000,
       options,
     });
+
+    if (options?.updateDbNamespace) {
+      this._db.useNamespace(namespace);
+    }
   }
 
   /**

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

@@ -19,7 +19,7 @@ import { Db } from '@/src/data-api';
 import { DbAdmin } from '@/src/devops/db-admin';
 import { WithTimeout } from '@/src/common/types';
 import { validateAdminOpts } from '@/src/devops/utils';
-import { CreateNamespaceOptions } from '@/src/devops/types/db-admin/create-namespace';
+import { LocalCreateNamespaceOptions } from '@/src/devops/types/db-admin/local-create-namespace';
 
 /**
  * An administrative class for managing non-Astra databases, including creating, listing, and deleting namespaces.
@@ -130,14 +130,14 @@ export class DataAPIDbAdmin extends DbAdmin {
    * ```typescript
    * await dbAdmin.createNamespace('my_namespace');
    *
-   * await dbAdmin.createNamespace('my_namespace' {
+   * await dbAdmin.createNamespace('my_namespace', {
    *   replication: {
    *     class: 'SimpleStrategy',
    *     replicatonFactor: 3,
    *   },
    * });
    *
-   * await dbAdmin.createNamespace('my_namespace' {
+   * await dbAdmin.createNamespace('my_namespace', {
    *   replication: {
    *     class: 'NetworkTopologyStrategy',
    *     datacenter1: 3,
@@ -151,12 +151,17 @@ export class DataAPIDbAdmin extends DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  public override async createNamespace(namespace: string, options?: CreateNamespaceOptions): Promise<void> {
+  public override async createNamespace(namespace: string, options?: LocalCreateNamespaceOptions): Promise<void> {
     const replication = options?.replication ?? {
       class: 'SimpleStrategy',
       replicationFactor: 1,
     };
+
     await this._httpClient.executeCommand({ createNamespace: { name: namespace, options: { replication } } }, { maxTimeMS: options?.maxTimeMS });
+
+    if (options?.updateDbNamespace) {
+      this._db.useNamespace(namespace);
+    }
   }
 
   /**

src/devops/db-admin.ts

@@ -13,7 +13,7 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { AdminBlockingOptions } from '@/src/devops/types';
+import { AdminBlockingOptions, CreateNamespaceOptions } from '@/src/devops/types';
 import { Db } from '@/src/data-api';
 
 /**
@@ -92,7 +92,7 @@ export abstract class DbAdmin {
    *
    * @returns A promise that resolves when the operation completes.
    */
-  abstract createNamespace(namespace: string, options?: AdminBlockingOptions): Promise<void>;
+  abstract createNamespace(namespace: string, options?: CreateNamespaceOptions): Promise<void>;
   /**
    * Drops a namespace (aka keyspace) from this database.
    *