Minor testing, bug fixes, and changes

Author: toptobes

.env.example

@@ -4,8 +4,8 @@ ASTRA_URI=https://<db_id>-<region>.apps.astra.datastax.com
 # Application token, used to authenticate with the Astra API
 APPLICATION_TOKEN=AstraCS:<rest_of_token>
 
-# Set this to some value to enable running tests that require a dev environment (make sure you're actually using the dev environment!!)
-ASTRA_RUN_DEV_TESTS=
+# Set this to some value to enable running tests that require a $vectorize enabled environment
+ASTRA_RUN_VECTORIZE_TESTS=
 
 # Set this to some value to enable running long-running tests
 ASTRA_RUN_LONG_TESTS=

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

@@ -127,14 +127,6 @@ export function replacer(this: any, key: string, value: any): any {
   }
 
   if (typeof this[key] === 'object') {
-    if (value instanceof ObjectId) {
-      return { $objectId: value.toString() };
-    }
-
-    if (value instanceof UUID) {
-      return { $uuid: value.toString() };
-    }
-
     if (key === '$date') {
       return new Date(value).valueOf();
     }

src/data-api/collection.ts

@@ -353,7 +353,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    * @see StrictFilter
    * @see StrictUpdateFilter
    */
-  public async updateOne(filter: Filter<Schema>, update: UpdateFilter<Schema>, options?: UpdateOneOptions<Schema>): Promise<UpdateOneResult> {
+  public async updateOne(filter: Filter<Schema>, update: UpdateFilter<Schema>, options?: UpdateOneOptions<Schema>): Promise<UpdateOneResult<Schema>> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: UpdateOneCommand = {
@@ -383,7 +383,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
         upsertedId: resp.status?.upsertedId,
         upsertedCount: 1,
       }
-      : commonResult;
+      : {
+        ...commonResult,
+        upsertedCount: 0,
+      };
   }
 
   /**
@@ -438,7 +441,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    * @see StrictFilter
    * @see StrictUpdateFilter
    */
-  public async updateMany(filter: Filter<Schema>, update: UpdateFilter<Schema>, options?: UpdateManyOptions): Promise<UpdateManyResult> {
+  public async updateMany(filter: Filter<Schema>, update: UpdateFilter<Schema>, options?: UpdateManyOptions): Promise<UpdateManyResult<SomeDoc>> {
     const command: UpdateManyCommand = {
       updateMany: {
         filter,
@@ -454,6 +457,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
     const commonResult = {
       modifiedCount: 0,
       matchedCount: 0,
+      upsertedCount: <const>0,
     };
 
     let resp;
@@ -473,6 +477,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
 
       commonResult.modifiedCount += desc.rawResponse?.status?.modifiedCount ?? 0;
       commonResult.matchedCount += desc.rawResponse?.status?.matchedCount ?? 0;
+      commonResult.upsertedCount = desc.rawResponse?.status?.upsertedCount ?? 0;
 
       throw mkRespErrorFromResponse(UpdateManyError, command, desc.rawResponse, commonResult);
     }
@@ -536,7 +541,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @see StrictFilter
    */
-  public async replaceOne(filter: Filter<Schema>, replacement: NoId<Schema>, options?: ReplaceOneOptions<Schema>): Promise<ReplaceOneResult> {
+  public async replaceOne(filter: Filter<Schema>, replacement: NoId<Schema>, options?: ReplaceOneOptions<Schema>): Promise<ReplaceOneResult<Schema>> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneAndReplaceCommand = {
@@ -567,7 +572,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
         upsertedId: resp.status?.upsertedId,
         upsertedCount: 1,
       }
-      : commonResult;
+      : {
+        ...commonResult,
+        upsertedCount: 0,
+      };
   }
 
   /**
@@ -1397,7 +1405,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @throws BulkWriteError - If the operation fails
    */
-  public async bulkWrite(operations: AnyBulkWriteOperation<Schema>[], options?: BulkWriteOptions): Promise<BulkWriteResult> {
+  public async bulkWrite(operations: AnyBulkWriteOperation<Schema>[], options?: BulkWriteOptions): Promise<BulkWriteResult<Schema>> {
     const timeoutManager = this._httpClient.timeoutManager(options?.maxTimeMS)
 
     return (options?.ordered)
@@ -1589,7 +1597,7 @@ const insertMany = async <Schema>(httpClient: DataApiHttpClient, documents: unkn
 /**
  * @internal
  */
-const bulkWriteOrdered = async (httpClient: DataApiHttpClient, operations: AnyBulkWriteOperation<SomeDoc>[], timeoutManager: TimeoutManager): Promise<BulkWriteResult> => {
+const bulkWriteOrdered = async (httpClient: DataApiHttpClient, operations: AnyBulkWriteOperation<SomeDoc>[], timeoutManager: TimeoutManager): Promise<BulkWriteResult<SomeDoc>> => {
   const results = new BulkWriteResult();
   let i = 0;
 
@@ -1616,7 +1624,7 @@ const bulkWriteOrdered = async (httpClient: DataApiHttpClient, operations: AnyBu
 /**
  * @internal
  */
-const bulkWriteUnordered = async (httpClient: DataApiHttpClient, operations: AnyBulkWriteOperation<SomeDoc>[], concurrency: number, timeoutManager: TimeoutManager): Promise<BulkWriteResult> => {
+const bulkWriteUnordered = async (httpClient: DataApiHttpClient, operations: AnyBulkWriteOperation<SomeDoc>[], concurrency: number, timeoutManager: TimeoutManager): Promise<BulkWriteResult<SomeDoc>> => {
   const results = new BulkWriteResult();
   let masterIndex = 0;
 
@@ -1654,7 +1662,7 @@ const bulkWriteUnordered = async (httpClient: DataApiHttpClient, operations: Any
   return results;
 }
 
-const bulkWrite = async (httpClient: DataApiHttpClient, operation: AnyBulkWriteOperation<SomeDoc>, results: BulkWriteResult, i: number, timeoutManager: TimeoutManager): Promise<void> => {
+const bulkWrite = async (httpClient: DataApiHttpClient, operation: AnyBulkWriteOperation<SomeDoc>, results: BulkWriteResult<SomeDoc>, i: number, timeoutManager: TimeoutManager): Promise<void> => {
   const command = buildBulkWriteCommand(operation);
   const resp = await httpClient.executeCommand(command, { timeoutManager });
   addToBulkWriteResult(results, resp.status!, i);
@@ -1685,8 +1693,8 @@ const buildBulkWriteCommand = (operation: AnyBulkWriteOperation<SomeDoc>): Recor
 /**
  * @internal
  */
-const addToBulkWriteResult = (result: BulkWriteResult, resp: Record<string, any>, i: number) => {
-  const asMutable = result as Mutable<BulkWriteResult>;
+const addToBulkWriteResult = (result: BulkWriteResult<SomeDoc>, resp: Record<string, any>, i: number) => {
+  const asMutable = result as Mutable<BulkWriteResult<SomeDoc>>;
 
   asMutable.insertedCount += resp.insertedIds?.length ?? 0;
   asMutable.modifiedCount += resp.modifiedCount ?? 0;

src/data-api/cursor.ts

@@ -17,8 +17,8 @@ import {
   FindOptions,
   InternalFindOptions,
   InternalGetMoreCommand,
-  ProjectionOption,
-  SortOption,
+  StrictProjection,
+  StrictSort,
 } from '@/src/data-api/types';
 import { CursorAlreadyInitializedError, SomeDoc } from '@/src/data-api';
 import { DataApiHttpClient } from '@/src/api';
@@ -141,7 +141,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @return The cursor.
    */
-  sort(sort: SortOption<TRaw>): FindCursor<T, TRaw> {
+  sort(sort: StrictSort<TRaw>): FindCursor<T, TRaw> {
     this._assertUninitialized();
     this._options.sort = sort;
     return this;
@@ -215,7 +215,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @return The cursor.
    */
-  project<R = any>(projection: ProjectionOption<TRaw>): FindCursor<R, TRaw> {
+  project<R = any, RRaw extends SomeDoc = SomeDoc>(projection: StrictProjection<TRaw>): FindCursor<R, RRaw> {
     this._assertUninitialized();
     this._options.projection = projection;
     return this as any;

src/data-api/db.ts

@@ -15,7 +15,6 @@
 import { Collection, CollectionAlreadyExistsError, extractDbIdFromUrl, SomeDoc } from '@/src/data-api';
 import { DataApiHttpClient, DEFAULT_DATA_API_PATH, DEFAULT_NAMESPACE, RawDataApiResponse } from '@/src/api';
 import {
-  CollectionName,
   CreateCollectionCommand,
   CreateCollectionOptions,
   FullCollectionInfo,
@@ -381,7 +380,7 @@ export class Db implements Disposable {
    *
    * @see CollectionOptions
    */
-  public async listCollections(options?: ListCollectionsOptions & { nameOnly?: true }): Promise<CollectionName[]>
+  public async listCollections(options: ListCollectionsOptions & { nameOnly: true }): Promise<string[]>
 
   /**
    * Lists the collections in the database.
@@ -402,22 +401,19 @@ export class Db implements Disposable {
    *
    * @see CollectionOptions
    */
-  public async listCollections(options?: ListCollectionsOptions & { nameOnly: false }): Promise<FullCollectionInfo[]>
+  public async listCollections(options?: ListCollectionsOptions & { nameOnly?: false }): Promise<FullCollectionInfo[]>
 
-  public async listCollections(options?: ListCollectionsOptions): Promise<CollectionName[] | FullCollectionInfo[]> {
+  public async listCollections(options?: ListCollectionsOptions): Promise<string[] | FullCollectionInfo[]> {
     const command: ListCollectionsCommand = {
       findCollections: {
         options: {
-          explain: options?.nameOnly === false,
+          explain: options?.nameOnly !== true,
         }
       },
     }
 
     const resp = await this._httpClient.executeCommand(command, options);
-
-    return (options?.nameOnly !== false)
-      ? resp.status!.collections.map((name: string) => ({ name }))
-      : resp.status!.collections;
+    return resp.status!.collections;
   }
 
   /**

src/data-api/errors.ts

@@ -17,6 +17,7 @@ import type { DeleteManyResult } from '@/src/data-api/types/delete/delete-many';
 import type { UpdateManyResult } from '@/src/data-api/types/update/update-many';
 import type { BulkWriteResult } from '@/src/data-api/types/misc/bulk-write';
 import type { RawDataApiResponse } from '@/src/api';
+import { SomeDoc } from '@/src/data-api/document';
 
 /**
  * An object representing a single "soft" (2XX) error returned from the Data API, typically with an error code and a
@@ -316,7 +317,7 @@ export class DeleteManyError extends CumulativeDataAPIError {
  */
 export class UpdateManyError extends CumulativeDataAPIError {
   name = 'UpdateManyError';
-  declare public readonly partialResult: UpdateManyResult;
+  declare public readonly partialResult: UpdateManyResult<SomeDoc>;
 }
 
 /**
@@ -335,7 +336,7 @@ export class UpdateManyError extends CumulativeDataAPIError {
  */
 export class BulkWriteError extends CumulativeDataAPIError {
   name = 'BulkWriteError';
-  declare public readonly partialResult: BulkWriteResult;
+  declare public readonly partialResult: BulkWriteResult<SomeDoc>;
 }
 
 /** @internal */

src/data-api/ids.ts

@@ -134,6 +134,14 @@ export class UUID {
   public inspect(): string {
     return `UUID("${this.toString()}")`;
   }
+
+  // noinspection JSUnusedGlobalSymbols
+  /**
+   * @internal
+   */
+  public toJSON() {
+    return { $uuid: this.toString() };
+  }
 }
 
 const objectIdRegex = new RegExp('^[0-9a-fA-F]{24}$');
@@ -237,6 +245,14 @@ export class ObjectId {
   public inspect(): string {
     return `ObjectId("${this.toString()}")`;
   }
+
+  // noinspection JSUnusedGlobalSymbols
+  /**
+   * @internal
+   */
+  public toJSON() {
+    return { $objectId: this.toString() };
+  }
 }
 
 /**

src/data-api/types/collections/list-collection.ts

@@ -56,21 +56,6 @@ export interface ListCollectionsOptions extends WithTimeout, WithNamespace {
   nameOnly?: boolean,
 }
 
-/**
- * The name of a collection, used when `nameOnly` is true or undefined in {@link ListCollectionsOptions}.
- *
- * @field name - The name of the collection.
- *
- * @see ListCollectionsOptions
- * @see Db.listCollections
- */
-export interface CollectionName {
-  /**
-   * The name of the collection.
-   */
-  name: string,
-}
-
 /**
  * Information about a collection, used when `nameOnly` is false in {@link ListCollectionsOptions}.
  *

src/data-api/types/common.ts

@@ -17,6 +17,14 @@ import type { ToDotNotation } from '@/src/data-api/types';
 
 export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId;
 
+export type Sort =
+  | Record<string, 1 | -1>
+  | { $vector: { $meta: number[] } }
+  | { $vector: number[] }
+  | { $vectorize: string };
+
+export type Projection = Record<string, 1 | 0 | true | false | Slice>;
+
 /**
  * Specifies the sort criteria for selecting documents.
  *
@@ -27,18 +35,18 @@ export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId
  * @example
  * ```typescript
  * // Sort by name in ascending order, then by age in descending order
- * const sort1: SortOption<SomeDoc> = {
+ * const sort1: StrictSort<SomeDoc> = {
  *   name: 1,
  *   age: -1,
  * }
  *
  * // Sort by vector distance
- * const sort2: SortOption<SomeDoc> = {
+ * const sort2: StrictSort<SomeDoc> = {
  *   $vector: [0.23, 0.38, 0.27, 0.91, 0.21],
  * }
  * ```
  */
-export type SortOption<Schema extends SomeDoc> =
+export type StrictSort<Schema extends SomeDoc> =
   | { [K in keyof ToDotNotation<Schema>]?: 1 | -1 }
   | { $vector: { $meta: number[] } }
   | { $vector: number[] }
@@ -52,24 +60,24 @@ export type SortOption<Schema extends SomeDoc> =
  * @example
  * ```typescript
  * // Include _id, name, and address.state
- * const projection1: ProjectionOption<SomeDoc> = {
+ * const projection1: StrictProjection<SomeDoc> = {
  *   _id: 1,
  *   name: 1,
  *   'address.state': 1,
  * }
  *
  * // Exclude the $vector
- * const projection2: ProjectionOption<SomeDoc> = {
+ * const projection2: StrictProjection<SomeDoc> = {
  *   $vector: 0,
  * }
  *
  * // Return array indices 2, 3, 4, and 5
- * const projection3: ProjectionOption<SomeDoc> = {
+ * const projection3: StrictProjection<SomeDoc> = {
  *   test_scores: { $slice: [2, 4] },
  * }
  * ```
  */
-export type ProjectionOption<Schema extends SomeDoc> = {
+export type StrictProjection<Schema extends SomeDoc> = {
   [K in keyof ToDotNotation<Schema> | '_id']?: any[] extends (ToDotNotation<Schema> & { _id: any })[K]
     ? 1 | 0 | true | false | Slice
     : 1 | 0 | true | false;

src/data-api/types/delete/delete-one.ts

@@ -13,14 +13,14 @@
 // limitations under the License.
 
 import type { SomeDoc } from '@/src/data-api';
-import type { SortOption } from '@/src/data-api/types';
+import type { StrictSort } from '@/src/data-api/types';
 import { WithTimeout } from '@/src/common/types';
 
 /** @internal */
 export interface DeleteOneCommand {
   deleteOne: {
     filter: Record<string, unknown>;
-    sort?: SortOption<any>;
+    sort?: StrictSort<any>;
   };
 }
 
@@ -41,7 +41,7 @@ export interface DeleteOneOptions<Schema extends SomeDoc> extends WithTimeout {
    * Defaults to `null`, where the order is not guaranteed.
    * @defaultValue null
    */
-  sort?: SortOption<Schema>,
+  sort?: StrictSort<Schema>,
   /**
    * An optional vector to use of the appropriate dimensionality to perform an ANN vector search on the collection
    * to find the closest matching document.