Further fixes and refactors for 1.4.0 (#63)

* headers integration testing

* better encapsulation on the core classes

* updated non-astra example to use updateDbNamespace

* reinstated example deps to npm versions

* overhauled how tests run

* added some missing typescript lang specifiers in tsdoc examples

* throw error on missing namespace

* more work on test overhaul

* tiny bit of tweaking to the test script

* commented test script a bit

* version script + increase a tests timeout

* a

* change default test timeout to 1m

* use export type where possible

* tiny tweak to build script

* update to build pipeline to delete "empty" files

* fixed bug with datapidbadmin

* fixed a couple documentation errors

* reverted example deps to npm versions

* added exit to if invalid flag passed to test script

* better help/error msg for test script

* updated vectorize tests to work with non-astra

* updated vectorize tests to work with bedrock

* linting fix

* added missing export

Author: toptobes

.np-config.json

@@ -1,3 +1,3 @@
 {
-  "testScript": "test:prerelease"
+  "testScript": "test -- --prerelease"
 }

DEVGUIDE.md

@@ -10,6 +10,12 @@ Prerequisites:
 - A clean AstraDB instance with two keyspaces—`default_keyspace` and `other_keyspace`
 - Copy the `.env.example` file and create a new `.env` file following the example template
 
+```shell
+npm run test -- [--all | --light | --coverage | --prerelease] [-f <filter>] [-b] [--args <raw_args>]
+# or
+npm run test -- <--types>
+```
+
 ```shell
 # Run both unit and integration tests
 npm run test
@@ -20,10 +26,21 @@ npm run test -- -f 'unit.'
 # Run only integration tests
 npm run test -- -f 'integration.'
 
+# Run all possible tests
+npm run test -- --all
+
+# Run all possible integration tests
+npm run test -- --all -f 'integration.'
+
+# Run all tests that aren't admin/long/vectorize
+npm run test -- --light -f 'integration.'
+
 # Run tsc with the noEmit flag to check for type errors
-npm run test:types
+npm run test -- --types
 ```
 
+(bun does not need the extra initial `--` like npm does)
+
 ### Running the tests on local Stargate
 You can do `sh scripts/start-stargate-4-tests.sh` to spin up an ephemeral Data API on DSE instance which automatically
 creates the required keyspaces and destroys itself on exit.
@@ -56,11 +73,6 @@ env ASTRA_RUN_LONG_TESTS=1 npm run test
 
 The `PROD` and `DEV` tags are enabled/disabled automatically, inferred from the astra endpoint URL.
 
-Use the following to run tests with ADMIN and LONG tags automatically enabled (note that doesn't include vectorize tests):
-```shell
-npm run test:all
-```
-
 ### Adding your own tagged tests
 To enforce the tags, use the `assertTestsEnabled` function from `test/fixtures.ts`, which will skip the function if the
 given tag is not enabled. 
@@ -122,10 +134,10 @@ See `vectorize_credentials.example.json` for—guess what—an example.
 
 To run coverage testing, run the following command:
 ```shell
-npm run test:coverage
+npm run test -- --coverage
 ```
 
-This uses `test:all` under the hood, as well as a "bail early" flag as there's not really a point continuing to run 
+This uses `test --all` under the hood, as well as a "bail early" flag as there's not really a point continuing to run 
 tests if one of them fails, as the coverage report will be impacted.
 
 ## Linting
@@ -143,5 +155,5 @@ To build it, just run `npm run build`, which does the following:
 - Deletes any extraneous `.d.ts` files
 
 ## Publishing
-I heavily recommend using [np](https://github.com/sindresorhus/np) to publish the package. Running it will involve running `test:prerelease`, and the
+I heavily recommend using [np](https://github.com/sindresorhus/np) to publish the package. Running it will involve running `test --prerelease`, and the
 versioning step will update the api report + update the version in `src/version.ts`. 

etc/astra-db-ts.api.md

@@ -120,6 +120,7 @@ export class AstraDbAdmin extends DbAdmin {
     db(): Db;
     drop(options?: AdminBlockingOptions): Promise<void>;
     dropNamespace(namespace: string, options?: AdminBlockingOptions): Promise<void>;
+    findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult>;
     get id(): string;
     info(options?: WithTimeout): Promise<FullDatabaseInfo>;
     listNamespaces(options?: WithTimeout): Promise<string[]>;
@@ -227,6 +228,14 @@ export class CollectionAlreadyExistsError extends DataAPIError {
     readonly namespace: string;
 }
 
+// @public
+export class CollectionNotFoundError extends DataAPIError {
+    // @internal
+    constructor(namespace: string, collectionName: string);
+    readonly collectionName: string;
+    readonly namespace: string;
+}
+
 // @public
 export interface CollectionOptions<Schema extends SomeDoc> {
     defaultId?: DefaultIdOptions;
@@ -380,6 +389,7 @@ export class DataAPIDbAdmin extends DbAdmin {
     createNamespace(namespace: string, options?: LocalCreateNamespaceOptions): Promise<void>;
     db(): Db;
     dropNamespace(namespace: string, options?: AdminBlockingOptions): Promise<void>;
+    findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult>;
     listNamespaces(options?: WithTimeout): Promise<string[]>;
 }
 
@@ -407,6 +417,15 @@ export interface DataAPIErrorDescriptor {
     readonly message?: string;
 }
 
+// @public
+export class DataAPIHttpError extends DataAPIError {
+    // @internal
+    constructor(resp: FetcherResponseInfo);
+    readonly body?: string;
+    readonly raw: FetcherResponseInfo;
+    readonly status: number;
+}
+
 // @public
 export type DataAPIHttpOptions = DefaultHttpClientOptions | FetchHttpClientOptions | CustomHttpClientOptions;
 
@@ -541,6 +560,7 @@ export abstract class DbAdmin {
     abstract createNamespace(namespace: string, options?: CreateNamespaceOptions): Promise<void>;
     abstract db(): Db;
     abstract dropNamespace(namespace: string, options?: AdminBlockingOptions): Promise<void>;
+    abstract findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult>;
     abstract listNamespaces(): Promise<string[]>;
 }
 
@@ -560,12 +580,6 @@ export interface DbSpawnOptions {
     token?: string | TokenProvider | null;
 }
 
-// @public
-export class EmbeddingAPIKeyHeaderProvider extends EmbeddingHeadersProvider {
-    constructor(apiKey: string | nullish);
-    getHeaders(): Record<string, string>;
-}
-
 // @public
 export interface DefaultHttpClientOptions {
     client?: 'default';
@@ -654,13 +668,57 @@ export class DevOpsUnexpectedStateError extends DevOpsAPIError {
 export interface DropCollectionOptions extends WithTimeout, WithNamespace {
 }
 
+// @public
+export class EmbeddingAPIKeyHeaderProvider extends EmbeddingHeadersProvider {
+    constructor(apiKey: string | nullish);
+    getHeaders(): Record<string, string>;
+}
+
 // @public
 export abstract class EmbeddingHeadersProvider {
     abstract getHeaders(): Promise<Record<string, string>> | Record<string, string>;
     // @internal
     static parseHeaders(token: unknown): EmbeddingHeadersProvider;
 }
 
+// @public
+export interface EmbeddingProviderAuthInfo {
+    enabled: boolean;
+    tokens: EmbeddingProviderTokenInfo[];
+}
+
+// @public
+export interface EmbeddingProviderInfo {
+    displayName: string;
+    models: EmbeddingProviderModelInfo[];
+    parameters: EmbeddingProviderParameterInfo[];
+    supportedAuthentication: Record<string, EmbeddingProviderAuthInfo>;
+    url: string;
+}
+
+// @public
+export interface EmbeddingProviderModelInfo {
+    name: string;
+    parameters: EmbeddingProviderParameterInfo[];
+    vectorDimension: number | null;
+}
+
+// @public
+export interface EmbeddingProviderParameterInfo {
+    defaultValue: string;
+    help: string;
+    name: string;
+    required: boolean;
+    type: string;
+    validation: Record<string, unknown>[];
+}
+
+// @public
+export interface EmbeddingProviderTokenInfo {
+    accepted: string;
+    forwarded: string;
+}
+
 // @public
 export class FailedToLoadDefaultClientError extends Error {
     // @internal
@@ -757,6 +815,11 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
     toArray(): Promise<T[]>;
 }
 
+// @public
+export interface FindEmbeddingProvidersResult {
+    embeddingProviders: Record<string, EmbeddingProviderInfo>;
+}
+
 // @public
 export interface FindOneAndDeleteOptions extends WithTimeout {
     includeResultMetadata?: boolean;
@@ -1321,7 +1384,6 @@ export interface VectorizeServiceOptions {
 export interface VectorOptions {
     dimension?: number;
     metric?: 'cosine' | 'euclidean' | 'dot_product';
-    // @alpha
     service?: VectorizeServiceOptions;
 }
 

package.json

@@ -49,14 +49,10 @@
   },
   "scripts": {
     "lint": "eslint src/* tests/*",
-    "test": "ts-mocha --paths -p tsconfig.json tests/unit/**/*.test.ts tests/integration/**/*.test.ts tests/integration/**/**/*.test.ts",
-    "test:all": "env ASTRA_RUN_LONG_TESTS=1 ASTRA_RUN_ADMIN_TESTS=1 ts-mocha --paths -p tsconfig.json tests/unit/**/*.test.ts tests/integration/**/*.test.ts tests/integration/**/**/*.test.ts",
-    "test:coverage": "nyc npm run test:all -- -b",
-    "test:types": "tsc --noEmit --skipLibCheck",
-    "test:prerelease": "npm run lint && npm run test:types && npm run test:all -- -b --exit",
-    "build": "sh ./scripts/build.sh",
+    "test": "sh scripts/test.sh",
+    "build": "sh scripts/build.sh",
     "list-embedding-providers": "chmod +x scripts/list-embedding-providers.sh && scripts/list-embedding-providers.sh",
-    "version": "npm run build && git add src/version.ts etc/astra-db-ts.api.md"
+    "version": "sh scripts/version.sh"
   },
   "bugs": {
     "url": "https://github.com/datastax/astra-ts-client/issues"

scripts/build.sh

@@ -7,21 +7,27 @@ rm -rf ./dist
 node scripts/build-version-file.js > src/version.ts
 
 # Transpiles the project
-yes | npx tsc --project tsconfig.build.json
+npx tsc --project tsconfig.build.json
 
 # Replaces alias paths with relative paths (e.g. `@/src/version` -> `../../src/version`)
-yes | npx tsc-alias -p tsconfig.build.json
+npx tsc-alias -p tsconfig.build.json
 
 # Creates the rollup .d.ts, generates an API report in etc/, and cleans up any temp files
-yes | npx api-extractor run -c ./api-extractor.jsonc --local && rm -r ./temp
+npx api-extractor run -c ./api-extractor.jsonc --local && rm -r ./temp
 
 # Uses a more succinct licence notice + removes block comments (the rollup .d.ts file already contains the ts-doc)
 find ./dist -type f -name '*.js' -exec node scripts/reduce-comments.js {} \;
 
 # Adds the missing license notice to the rollup .d.ts
 node scripts/add-license-bumf.js dist/astra-db-ts.d.ts
 
+# Delete the "empty" files where only types were declared
+node scripts/del-empty-dist-files.js
+
 # Removes all .d.ts files except the main rollup .d.ts
 cd dist || return 1
 find . -type f -name '*.d.ts' ! -name 'astra-db-ts.d.ts' -exec rm {} +
 cd ..
+
+# Delete any empty leftover directories
+find ./dist -type d -empty -delete

scripts/del-empty-dist-files.js

@@ -0,0 +1,43 @@
+const fs = require('fs');
+const path = require('path');
+
+const targetContent = `"use strict";
+// Copyright Datastax, Inc
+// SPDX-License-Identifier: Apache-2.0
+Object.defineProperty(exports, "__esModule", { value: true });
+`;
+
+function deleteEmptyFiles(dirPath) {
+  fs.readdir(dirPath, (err, files) => {
+    if (err) {
+      return console.error('Unable to scan directory: ' + err);
+    }
+
+    files.forEach(file => {
+      const filePath = path.join(dirPath, file);
+
+      fs.stat(filePath, (err, stat) => {
+        if (err) {
+          return console.error('Error stating file: ' + err);
+        }
+
+        if (stat.isDirectory()) {
+          deleteEmptyFiles(filePath);
+          return;
+        }
+
+        fs.readFile(filePath, 'utf8', (err, data) => {
+          if (err) {
+            return console.error('Error reading file: ' + err);
+          }
+
+          if (data === targetContent) {
+            fs.unlink(filePath, (err) => err && console.error('Error deleting file: ' + err));
+          }
+        });
+      });
+    });
+  });
+}
+
+deleteEmptyFiles('./dist');