Minor 1.3.0 updates (#49)

- `replaceOne` now uses `projection: { '*': 0 }` under the hood
- made `distinct` *much* faster
- added token providers
- extra bug fixes, refactoring, documentation, etc.

Author: toptobes

.eslintrc.cjs

@@ -1,6 +1,6 @@
 /* eslint-env node */
 module.exports = {
-  ignorePatterns: ['dist/*'],
+  ignorePatterns: ['dist/*', 'scripts/*'],
   extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
   parser: '@typescript-eslint/parser',
   plugins: ['@typescript-eslint'],

.gitignore

@@ -137,4 +137,4 @@ build.zip
 temp
 tsdoc-metadata.json
 
-tests/vectorize_credentials.json
+vectorize_credentials.json

DEVGUIDE.md

@@ -74,7 +74,7 @@ test suite harder to manage.
 
 ### Running vectorize tests
 To run vectorize tests, you need to have a vectorize-enabled kube running, with the correct tags enabled.
-You must create a file, `tests/vectorize_tests.json`, with the following format:
+You must create a file, `vectorize_tests.json`, in the root folder, with the following format:
 
 ```ts
 interface Config {

README.md

@@ -101,7 +101,8 @@ const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
 })();
 ```
 
-Next steps:
+### 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 reference](https://docs.datastax.com/en/astra/astra-db-vector/api-reference/data-api-commands.html)

etc/astra-db-ts.api.md

@@ -63,7 +63,7 @@ export class AdminCommandSucceededEvent extends AdminCommandEvent {
 
 // @public
 export interface AdminSpawnOptions {
-    adminToken?: string;
+    adminToken?: string | TokenProvider | null;
     endpointUrl?: string;
     monitorCommands?: boolean;
 }
@@ -101,11 +101,7 @@ export class AstraAdmin {
     // Warning: (ae-forgotten-export) The symbol "InternalRootClientOpts" needs to be exported by the entry point index.d.ts
     //
     // @internal
-    constructor(options: InternalRootClientOpts & {
-        adminOptions: {
-            adminToken: string;
-        };
-    });
+    constructor(options: InternalRootClientOpts);
     createDatabase(config: DatabaseConfig, options?: CreateDatabaseOptions): Promise<AstraDbAdmin>;
     db(endpoint: string, options?: DbSpawnOptions): Db;
     db(id: string, region: string, options?: DbSpawnOptions): Db;
@@ -333,7 +329,8 @@ export interface CustomHttpClientOptions {
 // @public
 export class DataAPIClient extends DataAPIClientEventEmitterBase {
     [Symbol.asyncDispose]: () => Promise<void>;
-    constructor(token: string, options?: DataAPIClientOptions | null);
+    constructor(options?: DataAPIClientOptions | nullish);
+    constructor(token: string | TokenProvider | nullish, options?: DataAPIClientOptions | nullish);
     admin(options?: AdminSpawnOptions): AstraAdmin;
     close(): Promise<void>;
     db(endpoint: string, options?: DbSpawnOptions): Db;
@@ -525,7 +522,7 @@ export interface DbSpawnOptions {
     dataApiPath?: string;
     monitorCommands?: boolean;
     namespace?: string;
-    token?: string;
+    token?: string | TokenProvider | null;
 }
 
 // @public
@@ -615,6 +612,12 @@ export class DevOpsUnexpectedStateError extends DevOpsAPIError {
 export interface DropCollectionOptions extends WithTimeout, WithNamespace {
 }
 
+// @public
+export class DSEUsernamePasswordTokenProvider extends TokenProvider {
+    constructor(username: string, password: string);
+    getTokenAsString(): Promise<string>;
+}
+
 // @public
 export class FailedToLoadDefaultClientError extends Error {
     // @internal
@@ -923,6 +926,9 @@ export interface NoUpsertUpdateOptions {
     upsertedId?: never;
 }
 
+// @public
+export type nullish = null | undefined;
+
 // @public
 export type NumberUpdate<Schema> = {
     [K in keyof Schema as IsNum<Schema[K]> extends true ? K : never]?: number | bigint;
@@ -1023,6 +1029,12 @@ export type Sort = Record<string, SortDirection> | {
 // @public
 export type SortDirection = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending';
 
+// @public
+export class StaticTokenProvider extends TokenProvider {
+    constructor(token: string);
+    getTokenAsString(): Promise<string>;
+}
+
 // @public
 export type StrictDateUpdate<Schema extends SomeDoc, InNotation = ToDotNotation<Schema>> = ContainsDate<InNotation> extends true ? {
     [K in keyof InNotation as ContainsDate<InNotation[K]> extends true ? K : never]?: Date | {
@@ -1110,6 +1122,13 @@ export interface StrictUpdateFilter<Schema extends SomeDoc> {
 // @public
 export type ToDotNotation<Schema extends SomeDoc> = Merge<_ToDotNotation<Schema, ''>>;
 
+// @public
+export abstract class TokenProvider {
+    abstract getTokenAsString(): Promise<string>;
+    // @internal
+    static parseToken(token: unknown): TokenProvider | nullish;
+}
+
 // @public
 export class TooManyDocumentsToCountError extends DataAPIError {
     // @internal

package-lock.json

@@ -56,6 +56,7 @@
     "test:prerelease": "npm run lint && npm run test:types && npm run test:all -- -b --exit",
     "api-extractor": "api-extractor run -c ./api-extractor.jsonc --local",
     "build": "sh ./scripts/build.sh",
+    "find-missing-licensing": "sh ./scripts/check-licensing.sh",
     "version": "npm run build && git add src/version.ts etc/astra-db-ts.api.md"
   },
   "bugs": {
@@ -78,7 +79,7 @@
   "dependencies": {
     "bson-objectid": "^2.0.4",
     "fetch-h2": "^3.0.2",
-    "object-hash": "^3.0.0",
+    "safe-stable-stringify": "^2.4.3",
     "typed-emitter": "^2.1.0",
     "uuidv7": "^0.6.3"
   },

package.json

@@ -0,0 +1,18 @@
+console.log([
+  `// Copyright DataStax, Inc.`,
+  `//`,
+  `// Licensed under the Apache License, Version 2.0 (the "License");`,
+  `// you may not use this file except in compliance with the License.`,
+  `// You may obtain a copy of the License at`,
+  `//`,
+  `// http://www.apache.org/licenses/LICENSE-2.0`,
+  `//`,
+  `// Unless required by applicable law or agreed to in writing, software`,
+  `// distributed under the License is distributed on an "AS IS" BASIS,`,
+  `// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.`,
+  `// See the License for the specific language governing permissions and`,
+  `// limitations under the License.`,
+  ``,
+  `export const LIB_NAME = 'astra-db-ts';`,
+  `export const LIB_VERSION = '${require('../package.json').version}';`,
+].join('\n'));

scripts/build-version-file.js

@@ -4,14 +4,13 @@
 rm -rf ./dist
 
 # Creates the version file
-echo "export const LIB_NAME = 'astra-db-ts';" > src/version.ts
-node -p "'export const LIB_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'" >> src/version.ts
+node scripts/build-version-file.js > src/version.ts
 
 # Transpiles the project
-npx tsc --project tsconfig.build.json
+yes | npx tsc --project tsconfig.build.json
 
 # Replaces alias paths with relative paths (e.g. `@/src/version` -> `../../src/version`)
-npx tsc-alias -p tsconfig.build.json
+yes | npx tsc-alias -p tsconfig.build.json
 
 # Creates the rollup .d.ts and generates an API report in etc/
 npm run api-extractor

scripts/build.sh

@@ -0,0 +1 @@
+find tests/ src/ -type f -exec grep -L "^// Copyright DataStax, Inc." {} +