More docs + renaming for client uniformity

Author: toptobes

README.md

@@ -15,16 +15,16 @@ Get the *API endpoint* and your *applicaton token* for your Astra DB instance @
 Try the following code after setting the following environment variables:
 
 ```typescript
-import { DataApiClient, VectorDoc, UUID, ObjectId } from '@datastax/astra-db-ts';
+import { DataAPIClient, VectorDoc, UUID, ObjectId } from '@datastax/astra-db-ts';
 
 // Schema for the collection (VectorDoc adds the $vector field)
 interface Idea extends VectorDoc {
   idea: string,
 }
 
 // Connect to the db
-const client = new DataApiClient('AstraCS:...');
-const db = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
+const client = new DataAPIClient('*TOKEN*');
+const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
 
 (async () => {
   // Creates collection, or gets it if it already exists with same options
@@ -86,7 +86,7 @@ const db = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
 Next steps:
 - More info and usage patterns are given in the ts-doc of classes and methods
 - [TS client reference](https://docs.datastax.com/en/astra/astra-db-vector/clients/typescript.html)
-- [Data API refernce](https://docs.datastax.com/en/astra/astra-db-vector/api-reference/data-api-commands.html)
+- [Data API reference](https://docs.datastax.com/en/astra/astra-db-vector/api-reference/data-api-commands.html)
 - Package on [npm](https://www.npmjs.com/package/@datastax/astra-db-ts)
 
 ## astra-db-ts's API
@@ -100,9 +100,10 @@ astra-db-ts's abstractions for working at the data and admin layers are structur
 Here's a small admin-oriented example:
 
 ```typescript
-import { DataApiClient } from '@datastax/astra-db-ts';
+import { DataAPIClient } from '@datastax/astra-db-ts';
 
-const client = new DataApiClient('AstraCS:...');
+// Spawn an admin 
+const client = new DataAPIClient('*TOKEN*');
 const admin = client.admin();
 
 (async () => {
@@ -122,16 +123,17 @@ const admin = client.admin();
 astra-db-ts exports an `ObjectId` and `UUID` class for working with these types in the database. Here's an example:
 
 ```typescript
-import { DataApiClient, ObjectId, UUID } from '@datastax/astra-db-ts';
+import { DataAPIClient, ObjectId, UUID } from '@datastax/astra-db-ts';
 
 interface Person {
   _id: ObjectId | UUID,
   name: string,
   friendId?: string,
 }
 
-const client = new DataApiClient('AstraCS:...');
-const db = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
+// Connect to the db
+const client = new DataAPIClient('*TOKEN*');
+const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
 
 (async () => {
   // Create a collection with a UUIDv7 as the default ID

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

@@ -13,15 +13,15 @@
 // limitations under the License.
 // noinspection ExceptionCaughtLocallyJS
 
-import { DEFAULT_NAMESPACE, DEFAULT_TIMEOUT, hrTimeMs, HttpClient, HttpMethods, RawDataApiResponse } from '@/src/api';
+import { DEFAULT_NAMESPACE, DEFAULT_TIMEOUT, hrTimeMs, HttpClient, HttpMethods, RawDataAPIResponse } from '@/src/api';
 import { DataAPIResponseError, DataAPITimeout, mkRespErrorFromResponse, ObjectId, UUID } from '@/src/data-api';
 import { MkTimeoutError, TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
 import { CommandFailedEvent, CommandStartedEvent, CommandSucceededEvent } from '@/src/data-api/events';
 
 /**
  * @internal
  */
-export interface DataApiRequestInfo {
+export interface DataAPIRequestInfo {
   url: string;
   collection?: string;
   namespace?: string;
@@ -37,7 +37,7 @@ type ExecuteCommandOptions = TimeoutOptions & {
 /**
  * @internal
  */
-export class DataApiHttpClient extends HttpClient {
+export class DataAPIHttpClient extends HttpClient {
   public collection?: string;
   public namespace?: string;
 
@@ -48,7 +48,7 @@ export class DataApiHttpClient extends HttpClient {
   public async executeCommand(command: Record<string, any>, options: ExecuteCommandOptions | undefined) {
     const timeoutManager = options?.timeoutManager ?? mkTimeoutManager(options?.maxTimeMS);
 
-    return await this._requestDataApi({
+    return await this._requestDataAPI({
       url: this.baseUrl,
       timeoutManager: timeoutManager,
       collection: options?.collection,
@@ -57,7 +57,7 @@ export class DataApiHttpClient extends HttpClient {
     });
   }
 
-  private async _requestDataApi(info: DataApiRequestInfo): Promise<RawDataApiResponse> {
+  private async _requestDataAPI(info: DataAPIRequestInfo): Promise<RawDataAPIResponse> {
     let started = 0;
 
     try {
@@ -124,7 +124,7 @@ const mkTimeoutErrorMaker = (timeout: number): MkTimeoutError => {
   return () => new DataAPITimeout(timeout);
 }
 
-const mkFauxErroredResponse = (message: string): RawDataApiResponse => {
+const mkFauxErroredResponse = (message: string): RawDataAPIResponse => {
   return { errors: [{ message }] };
 }
 

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

@@ -16,7 +16,7 @@ import { hrTimeMs, HttpClient } from '@/src/api/http-client';
 import { AxiosError, AxiosResponse } from 'axios';
 import { HTTPClientOptions, HttpMethodStrings } from '@/src/api/types';
 import { HTTP1AuthHeaderFactories, HTTP1Strategy } from '@/src/api/http1';
-import { DevopsApiResponseError, DevopsApiTimeout, DevopsUnexpectedStateError } from '@/src/devops/errors';
+import { DevOpsAPIResponseError, DevOpsAPITimeout, DevOpsUnexpectedStateError } from '@/src/devops/errors';
 import { AdminBlockingOptions } from '@/src/devops/types';
 import { MkTimeoutError, TimeoutManager, TimeoutOptions } from '@/src/api/timeout-managers';
 import { HttpMethods } from '@/src/api/constants';
@@ -30,7 +30,7 @@ import {
 /**
  * @internal
  */
-export interface DevopsApiRequestInfo {
+export interface DevOpsAPIRequestInfo {
   path: string,
   method: HttpMethodStrings,
   data?: Record<string, any>,
@@ -51,13 +51,13 @@ export interface LongRunningRequestInfo {
 /**
  * @internal
  */
-export class DevopsApiHttpClient extends HttpClient {
+export class DevOpsAPIHttpClient extends HttpClient {
   constructor(props: HTTPClientOptions) {
     super(props);
-    this.requestStrategy = new HTTP1Strategy(HTTP1AuthHeaderFactories.DevopsApi);
+    this.requestStrategy = new HTTP1Strategy(HTTP1AuthHeaderFactories.DevOpsAPI);
   }
 
-  public async request(req: DevopsApiRequestInfo, options: TimeoutOptions | undefined, started: number = 0): Promise<AxiosResponse> {
+  public async request(req: DevOpsAPIRequestInfo, options: TimeoutOptions | undefined, started: number = 0): Promise<AxiosResponse> {
     const isLongRunning = started !== 0;
 
     try {
@@ -95,11 +95,11 @@ export class DevopsApiHttpClient extends HttpClient {
       if (!(e instanceof AxiosError)) {
         throw e;
       }
-      throw new DevopsApiResponseError(e);
+      throw new DevOpsAPIResponseError(e);
     }
   }
 
-  public async requestLongRunning(req: DevopsApiRequestInfo, info: LongRunningRequestInfo): Promise<AxiosResponse> {
+  public async requestLongRunning(req: DevOpsAPIRequestInfo, info: LongRunningRequestInfo): Promise<AxiosResponse> {
     const timeoutManager = mkTimeoutManager(info.options?.maxTimeMS);
     const isLongRunning = info?.options?.blocking !== false;
 
@@ -123,7 +123,7 @@ export class DevopsApiHttpClient extends HttpClient {
     return resp;
   }
 
-  private async _awaitStatus(id: string, req: DevopsApiRequestInfo, info: LongRunningRequestInfo, timeoutManager: TimeoutManager, started: number): Promise<void> {
+  private async _awaitStatus(id: string, req: DevOpsAPIRequestInfo, info: LongRunningRequestInfo, timeoutManager: TimeoutManager, started: number): Promise<void> {
     if (info.options?.blocking === false) {
       return;
     }
@@ -153,7 +153,7 @@ export class DevopsApiHttpClient extends HttpClient {
       }
 
       if (!info.legalStates.includes(resp.data?.status)) {
-        const error = new DevopsUnexpectedStateError(`Created database is not in any legal state [${[info.target, ...info.legalStates].join(',')}]`, resp);
+        const error = new DevOpsUnexpectedStateError(`Created database is not in any legal state [${[info.target, ...info.legalStates].join(',')}]`, resp);
 
         if (this.monitorCommands) {
           this.emitter.emit('adminCommandFailed', new AdminCommandFailedEvent(req, true, error, started));
@@ -178,5 +178,5 @@ const mkTimeoutManager = (maxMs: number | undefined) => {
 }
 
 const mkTimeoutErrorMaker = (timeout: number): MkTimeoutError => {
-  return (info) => new DevopsApiTimeout(info.url, timeout);
+  return (info) => new DevOpsAPITimeout(info.url, timeout);
 }

src/api/http-client.ts

@@ -17,7 +17,7 @@ import { GuaranteedAPIResponse, HTTPClientOptions, HTTPRequestInfo, HTTPRequestS
 import { HTTP1AuthHeaderFactories, HTTP1Strategy } from '@/src/api/http1';
 import { HTTP2Strategy } from '@/src/api/http2';
 import { Mutable } from '@/src/data-api/types/utils';
-import { Caller, DataApiClientEvents } from '@/src/client';
+import { Caller, DataAPIClientEvents } from '@/src/client';
 import TypedEmitter from 'typed-emitter';
 
 /**
@@ -27,7 +27,7 @@ export class HttpClient {
   public readonly baseUrl: string;
   public readonly userAgent: string;
   public requestStrategy: HTTPRequestStrategy;
-  public emitter: TypedEmitter<DataApiClientEvents>;
+  public emitter: TypedEmitter<DataAPIClientEvents>;
   public monitorCommands: boolean;
   #applicationToken: string;
 
@@ -42,7 +42,7 @@ export class HttpClient {
         ? options.requestStrategy :
       (options.useHttp2 !== false)
         ? new HTTP2Strategy(this.baseUrl)
-        : new HTTP1Strategy(HTTP1AuthHeaderFactories.DataApi);
+        : new HTTP1Strategy(HTTP1AuthHeaderFactories.DataAPI);
 
     if (options.baseApiPath) {
       this.baseUrl += '/' + options.baseApiPath;

src/api/http1.ts

@@ -33,10 +33,10 @@ const axiosAgent = axios.create({
  * @internal
  */
 export const HTTP1AuthHeaderFactories = {
-  DataApi(token: string) {
+  DataAPI(token: string) {
     return { [DEFAULT_DATA_API_AUTH_HEADER]: token };
   },
-  DevopsApi(token: string) {
+  DevOpsAPI(token: string) {
     return { [DEFAULT_DEVOPS_API_AUTH_HEADER]: `Bearer ${token}` };
   },
 }

src/api/timeout-managers.ts

@@ -35,7 +35,7 @@ export type TimeoutOptions = {
  * @example
  * ```typescript
  * const mkTimeoutError: MkTimeoutError = (info) => {
- *   return new DevopsApiTimeout(info.url, timeout);
+ *   return new DevOpsAPITimeout(info.url, timeout);
  * }
  * ```
  *

src/api/types.ts

@@ -16,7 +16,7 @@ import { Caller } from '@/src/client';
 import { TimeoutManager } from '@/src/api/timeout-managers';
 import { HttpMethods } from '@/src/api/constants';
 import TypedEmitter from 'typed-emitter';
-import { DataApiCommandEvents } from '@/src/data-api/events';
+import { DataAPICommandEvents } from '@/src/data-api/events';
 
 /**
  * @internal
@@ -29,11 +29,11 @@ export interface HTTPClientOptions {
   useHttp2?: boolean;
   requestStrategy?: HTTPRequestStrategy;
   userAgent?: string;
-  emitter: TypedEmitter<DataApiCommandEvents>;
+  emitter: TypedEmitter<DataAPICommandEvents>;
   monitorCommands: boolean;
 }
 
-export interface RawDataApiResponse {
+export interface RawDataAPIResponse {
   status?: Record<string, any>;
   errors?: any[];
   data?: Record<string, any>;

src/client/data-api-client.ts

@@ -17,11 +17,11 @@ import { AstraAdmin, mkAdmin } from '@/src/devops/astra-admin';
 import { AdminSpawnOptions, DbSpawnOptions, InternalRootClientOpts, RootClientOptions } from '@/src/client/types';
 import TypedEmitter from 'typed-emitter';
 import EventEmitter from 'events';
-import { DataApiCommandEvents } from '@/src/data-api/events';
+import { DataAPICommandEvents } from '@/src/data-api/events';
 import { AdminCommandEvents } from '@/src/devops';
 
-export type DataApiClientEvents =
-  & DataApiCommandEvents
+export type DataAPIClientEvents =
+  & DataAPICommandEvents
   & AdminCommandEvents
 
 /**
@@ -50,11 +50,11 @@ export type DataApiClientEvents =
  * console.log(await admin1.listDatabases());
  * ```
  */
-export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataApiClientEvents>) {
+export class DataAPIClient extends (EventEmitter as new () => TypedEmitter<DataAPIClientEvents>) {
   readonly #options: InternalRootClientOpts;
 
   /**
-   * Constructs a new instance of the {@link DataApiClient}.
+   * Constructs a new instance of the {@link DataAPIClient}.
    *
    * @param token - The default token to use when spawning new instances of {@link Db} or {@link AstraAdmin}.
    * @param options - The default options to use when spawning new instances of {@link Db} or {@link AstraAdmin}.
@@ -63,15 +63,15 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
     super();
 
     if (!token || typeof token as any !== 'string') {
-      throw new Error('A valid token is required to use the DataApiClient');
+      throw new Error('A valid token is required to use the DataAPIClient');
     }
 
     this.#options = {
       ...options,
-      dataApiOptions: {
+      dbOptions: {
         monitorCommands: false,
         token: token,
-        ...options?.dataApiOptions,
+        ...options?.dbOptions,
       },
       adminOptions: {
         monitorCommands: false,
@@ -91,7 +91,7 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
    * `https://<db_id>-<region>.apps.astra.datastax.com`, but it can be used with DSE or any other Data-API-compatible
    * endpoint.
    *
-   * The given options will override any default options set when creating the {@link DataApiClient} through
+   * The given options 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).
    *
    * @example
@@ -110,7 +110,7 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
    * instead.
    *
    * @param endpoint - The direct endpoint to use.
-   * @param options - Any options to override the default options set when creating the {@link DataApiClient}.
+   * @param options - Any options to override the default options set when creating the {@link DataAPIClient}.
    *
    * @returns A new {@link Db} instance.
    */
@@ -124,7 +124,7 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
    * This overload is purely for user convenience, but it **only supports using Astra as the underlying database**. For
    * DSE or any other Data-API-compatible endpoint, use the other overload instead.
    *
-   * The given options will override any default options set when creating the {@link DataApiClient} through
+   * The given options 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).
    *
    * @example
@@ -144,7 +144,7 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
    *
    * @param id - The database ID to use.
    * @param region - The region to use.
-   * @param options - Any options to override the default options set when creating the {@link DataApiClient}.
+   * @param options - Any options to override the default options set when creating the {@link DataAPIClient}.
    *
    * @returns A new {@link Db} instance.
    */
@@ -160,7 +160,7 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
    *
    * **NB. This method is only available for Astra databases.**
    *
-   * The given options will override any default options set when creating the {@link DataApiClient} through
+   * The given options 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).
    *
    * @example
@@ -172,7 +172,7 @@ export class DataApiClient extends (EventEmitter as new () => TypedEmitter<DataA
    * console.log(dbs);
    * ```
    *
-   * @param options - Any options to override the default options set when creating the {@link DataApiClient}.
+   * @param options - Any options to override the default options set when creating the {@link DataAPIClient}.
    *
    * @returns A new {@link AstraAdmin} instance.
    */