Misc 1.4.1 improvements (#68)

* made returnDocument optional

* permanent hack, do not revert

* made updateDbNamespace (somewhat) immedietly set

* vectorize tests warmupErr option

* minor linting fix

* refactoring of vectorize tests

* updated devguide slightly

* I think now it works

* Fixed some shit

* Fixed so the code compiles

* SHIT ===> GOLD

* just trolling the repo

* nix + direnv support

* changed flake to shell.nix (flake is overkill atm)

* add scripts to path via direnv

* organized the scripts dir a bit

* LUKASZ SUCKS

* ci test

* update to devguide to cover nix-shell + direnv support

* Errare humanum est.

* slghtly updated tsdoc for findOneAnd* returnDocument commands since it is now optional

* It's secret!

* freemasonry

* lol digg

Author: toptobes

.envrc

@@ -0,0 +1,12 @@
+# shellcheck shell=bash
+if ! has nix_direnv_version || ! nix_direnv_version 3.0.5; then
+  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.5/direnvrc" "sha256-RuwIS+QKFj/T9M2TFXScjBsLR6V3A17YVoEW/Q6AZ1w="
+fi
+
+if nix --version &> /dev/null; then
+  use nix
+fi
+
+PATH_add scripts
+
+dotenv_if_exists

.gitignore

@@ -139,3 +139,5 @@ tsdoc-metadata.json
 
 vectorize_test_spec.json
 etc/test-reports/
+
+.direnv

DEVGUIDE.md

@@ -1,6 +1,6 @@
 # DEVGUIDE.md
 
-##  Contents
+## Contents
 1. [Running the tests](#running-the-tests)
    1. [Prerequisites](#prerequisites)
    2. [I can't be bothered to read all of this](#i-cant-be-bothered-to-read-all-of-this)
@@ -12,6 +12,8 @@
 2. [Typechecking & Linting](#typechecking--linting)
 3. [Building the library](#building-the-library)
 4. [Publishing](#publishing)
+5. [Miscellaneous](#miscellaneous)
+    1. [nix-shell + direnv support](#nix-shell--direnv-support)
 
 ## Running the tests
 
@@ -198,6 +200,7 @@ type VectorizeTestSpec = {
     parameters?: {
       [modelNameRegex: string]: Record<string, string>,
     },
+    warmupErr?: string,
   },
 }
 ```
@@ -215,6 +218,8 @@ where:
    - optional if not required. `azureOpenAI`, for example, will need this.
 - `dimension` is also a mapping of model name regex to their corresponding dimensions, like the `parameters` field.
    - optional if not required. `huggingfaceDedicated`, for example, will need this.
+- `warmupErr` may be set if the provider errors on a cold start
+   - if set, the provider will be called in a `while (true)` loop until it stops throwing an error matching this message
 
 This file is .gitignore-d by default and will not be checked into VCS.
 
@@ -321,3 +326,15 @@ continue on to publish the package using `np --no-tests`.
 
 The versioning step will automatically update the api report + update the version in `src/version.ts`, so you don't
 need to worry about that.
+
+## Miscellaneous
+
+### nix-shell + direnv support
+
+This is in no way required, but just for convenience purposes, a `.envrc` file is present that will
+ - If you have nix, use the `shell.nix` to drop you into a nix-shell w/ `nodejs_20` & `jq`
+ - Ephemerally add the `scripts/` dir to `PATH`
+ - Ephemerally source `.env` into your shell
+
+In case you have `direnv` installed, but don't want to use this, you can of course simply do `direnv block` and never
+worry about any of this ever again.

etc/astra-db-ts.api.md

@@ -115,7 +115,7 @@ export class AstraAdmin {
 // @public
 export class AstraDbAdmin extends DbAdmin {
     // @internal
-    constructor(db: Db, rootOpts: InternalRootClientOpts, adminOpts: AdminSpawnOptions | undefined, dbToken: TokenProvider);
+    constructor(db: Db, rootOpts: InternalRootClientOpts, adminOpts: AdminSpawnOptions | undefined, dbToken: TokenProvider, endpoint: string);
     createNamespace(namespace: string, options?: CreateNamespaceOptions): Promise<void>;
     db(): Db;
     drop(options?: AdminBlockingOptions): Promise<void>;
@@ -186,7 +186,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
     countDocuments(filter: Filter<Schema>, upperBound: number, options?: WithTimeout): Promise<number>;
     // @deprecated
     deleteAll(options?: WithTimeout): Promise<void>;
-    deleteMany(filter?: Filter<Schema>, options?: WithTimeout): Promise<DeleteManyResult>;
+    deleteMany(filter: Filter<Schema>, options?: WithTimeout): Promise<DeleteManyResult>;
     deleteOne(filter?: Filter<Schema>, options?: DeleteOneOptions): Promise<DeleteOneResult>;
     distinct<Key extends string>(key: Key, filter?: Filter<Schema>): Promise<Flatten<(SomeDoc & ToDotNotation<FoundDoc<Schema>>)[Key]>[]>;
     drop(options?: WithTimeout): Promise<boolean>;
@@ -841,7 +841,7 @@ export interface FindOneAndDeleteOptions extends WithTimeout {
 export interface FindOneAndReplaceOptions extends WithTimeout {
     includeResultMetadata?: boolean;
     projection?: Projection;
-    returnDocument: 'before' | 'after';
+    returnDocument?: 'before' | 'after';
     sort?: Sort;
     upsert?: boolean;
     // @deprecated
@@ -854,7 +854,7 @@ export interface FindOneAndReplaceOptions extends WithTimeout {
 export interface FindOneAndUpdateOptions extends WithTimeout {
     includeResultMetadata?: boolean;
     projection?: Projection;
-    returnDocument: 'before' | 'after';
+    returnDocument?: 'before' | 'after';
     sort?: Sort;
     upsert?: boolean;
     // @deprecated
@@ -954,8 +954,17 @@ export type IndexingOptions<Schema extends SomeDoc> = {
     allow?: never;
 };
 
+// @public
+export interface InsertManyDocumentResponse<Schema extends SomeDoc> {
+    error?: DataAPIErrorDescriptor;
+    _id: IdOf<Schema>;
+    status: 'OK' | 'ERROR' | 'SKIPPED';
+}
+
 // @public
 export class InsertManyError extends CumulativeDataAPIError {
+    readonly documentResponses: InsertManyDocumentResponse<SomeDoc>[];
+    readonly failedCount: number;
     name: string;
     readonly partialResult: InsertManyResult<SomeDoc>;
 }

package.json

@@ -45,7 +45,7 @@
     "lint": "eslint src/* tests/*",
     "test": "sh scripts/test.sh",
     "build": "sh scripts/build.sh",
-    "version": "sh scripts/version.sh"
+    "version": "sh scripts/utils/version.sh"
   },
   "bugs": {
     "url": "https://github.com/datastax/astra-ts-client/issues"

scripts/build.sh

@@ -4,7 +4,7 @@
 rm -rf ./dist
 
 # Creates the version file
-node scripts/build-version-file.js > src/version.ts
+node scripts/utils/build-version-file.js > src/version.ts
 
 # Transpiles the project
 npx tsc --project tsconfig.build.json
@@ -16,13 +16,13 @@ npx tsc-alias -p tsconfig.build.json
 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 {} \;
+find ./dist -type f -name '*.js' -exec node scripts/utils/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
+node scripts/utils/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
+node scripts/utils/del-empty-dist-files.js
 
 # Removes all .d.ts files except the main rollup .d.ts
 cd dist || return 1

scripts/start-stargate-4-tests.sh

@@ -6,4 +6,4 @@ echo "CLIENT_DB_TOKEN=Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh"
 echo "CLIENT_DB_ENVIRONMENT=dse"
 echo
 
-docker-compose -f scripts/docker-compose-stargate.yml up
+docker-compose -f scripts/utils/docker-compose-stargate.yml up

scripts/add-license-bumf.js renamed to scripts/utils/add-license-bumf.js

@@ -14,5 +14,5 @@ console.log([
   `// limitations under the License.`,
   ``,
   `export const LIB_NAME = 'astra-db-ts';`,
-  `export const LIB_VERSION = '${require('../package.json').version}';`,
+  `export const LIB_VERSION = '${require('../../package.json').version}';`,
 ].join('\n'));