updating api-report now off by default

api-extractor.jsonc

@@ -142,7 +142,7 @@
     /**
      * (REQUIRED) Whether to generate an API report.
      */
-    "enabled": true
+    "enabled": true,
 
     /**
      * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
@@ -168,7 +168,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/temp/"
      */
-    // "reportFolder": "<projectFolder>/temp/",
+     "reportFolder": "<projectFolder>/temp/"
 
     /**
      * Specifies the folder where the temporary report file is written.  The file name portion is determined by

etc/astra-db-ts.api.md

@@ -140,7 +140,7 @@ export class AstraAdmin {
     dbInfo(id: string, options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbAdminInfo>;
     dropDatabase(db: Db | string, options?: AstraDropDatabaseOptions): Promise<void>;
     // (undocumented)
-    get _httpClient(): unknown;
+    get _httpClient(): OpaqueHttpClient;
     listDatabases(options?: ListAstraDatabasesOptions): Promise<AstraDbAdminInfo[]>;
 }
 
@@ -170,7 +170,7 @@ export class AstraDbAdmin extends DbAdmin {
     dropKeyspace(keyspace: string, options?: AstraDropKeyspaceOptions): Promise<void>;
     findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult>;
     // (undocumented)
-    get _httpClient(): unknown;
+    get _httpClient(): OpaqueHttpClient;
     get id(): string;
     info(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbAdminInfo>;
     listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]>;
@@ -407,7 +407,7 @@ export class Collection<WSchema extends SomeDoc = SomeDoc, RSchema extends WithI
     findOneAndDelete<TRaw extends SomeDoc = RSchema>(filter: CollectionFilter<WSchema>, options?: CollectionFindOneAndDeleteOptions): Promise<TRaw | null>;
     findOneAndReplace<TRaw extends SomeDoc = RSchema>(filter: CollectionFilter<WSchema>, replacement: NoId<WSchema>, options?: CollectionFindOneAndReplaceOptions): Promise<TRaw | null>;
     findOneAndUpdate(filter: CollectionFilter<WSchema>, update: CollectionUpdateFilter<WSchema>, options?: CollectionFindOneAndUpdateOptions): Promise<RSchema | null>;
-    get _httpClient(): unknown;
+    get _httpClient(): OpaqueHttpClient;
     insertMany(documents: readonly MaybeId<WSchema>[], options?: CollectionInsertManyOptions): Promise<CollectionInsertManyResult<RSchema>>;
     insertOne(document: MaybeId<WSchema>, options?: WithTimeout<'generalMethodTimeoutMs'>): Promise<CollectionInsertOneResult<RSchema>>;
     readonly keyspace: string;
@@ -877,7 +877,7 @@ export class DataAPIDbAdmin extends DbAdmin {
     dropKeyspace(keyspace: string, options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<void>;
     findEmbeddingProviders(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<FindEmbeddingProvidersResult>;
     // (undocumented)
-    get _httpClient(): unknown;
+    get _httpClient(): OpaqueHttpClient;
     listKeyspaces(options?: WithTimeout<'keyspaceAdminTimeoutMs'>): Promise<string[]>;
 }
 
@@ -1030,7 +1030,7 @@ export class Db {
     dropTable(name: string, options?: DropTableOptions): Promise<void>;
     dropTableIndex(name: string, options?: TableDropIndexOptions): Promise<void>;
     // (undocumented)
-    get _httpClient(): unknown;
+    get _httpClient(): OpaqueHttpClient;
     get id(): string;
     info(options?: WithTimeout<'databaseAdminTimeoutMs'>): Promise<AstraDbInfo>;
     get keyspace(): string;
@@ -1638,6 +1638,9 @@ export const oid: (id?: string | number | null) => ObjectId;
 // @public
 export type OneOrMany<T> = T | readonly T[];
 
+// @public
+export type OpaqueHttpClient = any;
+
 // @public (undocumented)
 export type PathCodec<Fns extends CodecSerDesFns> = {
     serialize?: Fns['serialize'];
@@ -1747,7 +1750,7 @@ export class Table<WSchema extends SomeRow, PKey extends SomeRow = Partial<Found
         projection?: never;
     }): Promise<WithSim<RSchema> | null>;
     findOne<TRaw extends SomeRow = Partial<RSchema>>(filter: TableFilter<WSchema>, options: TableFindOneOptions): Promise<TRaw | null>;
-    get _httpClient(): unknown;
+    get _httpClient(): OpaqueHttpClient;
     insertMany(rows: readonly WSchema[], options?: TableInsertManyOptions): Promise<TableInsertManyResult<PKey>>;
     insertOne(row: WSchema, timeout?: WithTimeout<'generalMethodTimeoutMs'>): Promise<TableInsertOneResult<PKey>>;
     readonly keyspace: string;

scripts/build.sh

@@ -1,13 +1,25 @@
 #!/usr/bin/env sh
 
+while [ $# -gt 0 ]; do
+  case "$1" in
+    "-gen-report" | "-r")
+      gen_report=true
+      ;;
+    "-light" | "-l")
+      light=true
+      ;;
+  esac
+  shift
+done
+
 # Cleans the previous build
 rm -rf ./dist
 
 # Creates the version file
 node scripts/utils/build-version-file.js > src/version.ts
 
 # Transpiles the project
-if [ "$1" = "-light" ]; then
+if [ "$light" = true ]; then
   npx tsc --project tsconfig.production.json -d false --noCheck
 else
   npx tsc --project tsconfig.production.json
@@ -16,16 +28,25 @@ fi
 # Replaces alias paths with relative paths (e.g. `@/src/version` -> `../../src/version`)
 npx tsc-alias -p tsconfig.production.json
 
-if [ "$1" != "-light" ]; then
+if [ "$light" != true ]; then
   # Creates the rollup .d.ts, generates an API report in etc/, and cleans up any temp files
-  npx api-extractor run -c ./api-extractor.jsonc --local && rm -r ./temp
+  npx api-extractor run -c ./api-extractor.jsonc --local
+
+  # Updates the API report if flag not set
+  if [ "$gen_report" = true ]; then
+    mv -f ./temp/*.api.md ./etc/
+  fi
+  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/utils/reduce-comments.js {} \;
 
   # Adds the missing license notice to the rollup .d.ts
   node scripts/utils/add-license-bumf.js dist/astra-db-ts.d.ts
 
+  # Protects against Symbol.asyncIterator not found
+  sed -i -E '/^(\s+)\[Symbol\.asyncIterator\]/i\// @ts-ignore-error - May or may not be found depending on TS version & esnext.disposable in lib' dist/astra-db-ts.d.ts
+
   # Delete the "empty" files where only types were declared
   node scripts/utils/del-empty-dist-files.js
 

scripts/check.sh

@@ -66,7 +66,7 @@ for check_type in $check_types; do
       echo "Checking library compiles..."
 
       tmp_dir="tmp-lib-check"
-      rm -rf "$tmp_dir"
+      rm -rf "$tmp_dir" "$main_dir/dist"
 
       (scripts/build.sh \
         && mkdir "$tmp_dir" \

src/administration/astra-admin.ts

@@ -23,7 +23,7 @@ import { Db } from '@/src/db/db';
 import { buildAstraDatabaseAdminInfo } from '@/src/administration/utils';
 import { DEFAULT_DEVOPS_API_ENDPOINTS, DEFAULT_KEYSPACE, HttpMethods } from '@/src/lib/api/constants';
 import { DevOpsAPIHttpClient } from '@/src/lib/api/clients/devops-api-http-client';
-import { TokenProvider, WithTimeout } from '@/src/lib';
+import { OpaqueHttpClient, TokenProvider, WithTimeout } from '@/src/lib';
 import { AstraDbAdminInfo } from '@/src/administration/types/admin/database-info';
 import { parseAdminSpawnOpts } from '@/src/client/parsers/spawn-admin';
 import { InternalRootClientOpts } from '@/src/client/types/internal';
@@ -480,7 +480,7 @@ export class AstraAdmin {
     });
   }
 
-  public get _httpClient(): unknown {
+  public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }
 }

src/administration/astra-db-admin.ts

@@ -15,7 +15,7 @@
 
 import { AstraCreateKeyspaceOptions, AstraDropKeyspaceOptions } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
-import type { WithTimeout } from '@/src/lib';
+import { OpaqueHttpClient, WithTimeout } from '@/src/lib';
 import { TokenProvider } from '@/src/lib';
 import { buildAstraDatabaseAdminInfo, extractAstraEnvironment } from '@/src/administration/utils';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
@@ -335,7 +335,7 @@ export class AstraDbAdmin extends DbAdmin {
     });
   }
 
-  public get _httpClient(): unknown {
+  public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }
 

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

@@ -15,7 +15,7 @@
 
 import { DataAPICreateKeyspaceOptions } from '@/src/administration/types';
 import { DbAdmin } from '@/src/administration/db-admin';
-import type { WithTimeout } from '@/src/lib';
+import type { OpaqueHttpClient, WithTimeout } from '@/src/lib';
 import { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers';
 import { DataAPIHttpClient } from '@/src/lib/api/clients/data-api-http-client';
 import { Db } from '@/src/db';
@@ -223,7 +223,7 @@ export class DataAPIDbAdmin extends DbAdmin {
     });
   }
 
-  public get _httpClient(): unknown {
+  public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }
 }

src/db/db.ts

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 import { Collection, FoundDoc, SomeDoc, WithId } from '@/src/documents/collections';
-import { DEFAULT_KEYSPACE, RawDataAPIResponse, WithTimeout } from '@/src/lib/api';
+import { DEFAULT_KEYSPACE, type OpaqueHttpClient, RawDataAPIResponse, WithTimeout } from '@/src/lib/api';
 import { AstraDbAdmin } from '@/src/administration/astra-db-admin';
 import { DataAPIEnvironment, nullish } from '@/src/lib/types';
 import { extractDbIdFromUrl, extractRegionFromUrl } from '@/src/documents/utils';
@@ -1214,7 +1214,7 @@ export class Db {
     });
   }
 
-  public get _httpClient(): unknown {
+  public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }
 }

src/documents/collections/collection.ts

@@ -43,7 +43,7 @@ import {
 } from '@/src/documents/collections/types';
 import { CollectionDefinition, CollectionOptions, Db } from '@/src/db';
 import { BigNumberHack, DataAPIHttpClient } from '@/src/lib/api/clients/data-api-http-client';
-import { WithTimeout } from '@/src/lib';
+import { type OpaqueHttpClient, WithTimeout } from '@/src/lib';
 import { CommandImpls } from '@/src/documents/commands/command-impls';
 import { $CustomInspect } from '@/src/lib/constants';
 import { CollectionInsertManyError, TooManyDocumentsToCountError, WithSim } from '@/src/documents';
@@ -1507,7 +1507,7 @@ export class Collection<WSchema extends SomeDoc = SomeDoc, RSchema extends WithI
   /**
    * Backdoor to the HTTP client for if it's absolutely necessary. Which it almost never (if even ever) is.
    */
-  public get _httpClient(): unknown {
+  public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }
 }

src/documents/tables/table.ts

@@ -31,7 +31,7 @@ import {
 import { BigNumberHack, DataAPIHttpClient } from '@/src/lib/api/clients/data-api-http-client';
 import { CommandImpls } from '@/src/documents/commands/command-impls';
 import { AlterTableOptions, Db, DropTableOptions, ListTableDefinition, TableOptions } from '@/src/db';
-import { WithTimeout } from '@/src/lib';
+import { type OpaqueHttpClient, WithTimeout } from '@/src/lib';
 import { $CustomInspect } from '@/src/lib/constants';
 import JBI from 'json-bigint';
 import { TableFindCursor } from '@/src/documents/tables/cursor';
@@ -1294,7 +1294,7 @@ export class Table<WSchema extends SomeRow, PKey extends SomeRow = Partial<Found
   /**
    * Backdoor to the HTTP client for if it's absolutely necessary. Which it almost never (if even ever) is.
    */
-  public get _httpClient(): unknown {
+  public get _httpClient(): OpaqueHttpClient {
     return this.#httpClient;
   }
 }

src/lib/api/index.ts

@@ -24,6 +24,7 @@ export type {
 
 export type {
   RawDataAPIResponse,
+  OpaqueHttpClient,
 } from './types';
 
 export type {

src/lib/api/types.ts

@@ -12,6 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * Unstable backdoor to some class's internal HTTP client. No guarantees are made about this type.
+ *
+ * @public
+ */
+export type OpaqueHttpClient = any;
+
 /**
  * The response format of a 2XX-status Data API call
  *