Split SortOption into Sort and StrictSort

Author: toptobes

src/data-api/collection.ts

@@ -269,10 +269,6 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
   public async insertMany(documents: MaybeId<Schema>[], options?: InsertManyOptions): Promise<InsertManyResult<Schema>> {
     const chunkSize = options?.chunkSize ?? 20;
 
-    if (options?.vectors && options?.vectorize) {
-      throw new Error('Cannot set both vectors and vectorize options');
-    }
-
     if (options?.vectors) {
       if (options.vectors.length !== documents.length) {
         throw new Error('The number of vectors must match the number of documents');
@@ -292,6 +288,9 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
 
       for (let i = 0, n = documents.length; i < n; i++) {
         if (options.vectorize[i]) {
+          if (documents[i].$vector) {
+            throw new Error('Vector and vectorize options cannot overlap');
+          }
           documents[i] = { ...documents[i], $vectorize: options.vectorize[i] };
         }
       }
@@ -353,7 +352,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<Schema>> {
+  public async updateOne(filter: Filter<Schema>, update: UpdateFilter<Schema>, options?: UpdateOneOptions): Promise<UpdateOneResult<Schema>> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: UpdateOneCommand = {
@@ -541,7 +540,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @see StrictFilter
    */
-  public async replaceOne(filter: Filter<Schema>, replacement: NoId<Schema>, options?: ReplaceOneOptions<Schema>): Promise<ReplaceOneResult<Schema>> {
+  public async replaceOne(filter: Filter<Schema>, replacement: NoId<Schema>, options?: ReplaceOneOptions): Promise<ReplaceOneResult<Schema>> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneAndReplaceCommand = {
@@ -608,7 +607,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @see StrictFilter
    */
-  public async deleteOne(filter: Filter<Schema> = {}, options?: DeleteOneOptions<Schema>): Promise<DeleteOneResult> {
+  public async deleteOne(filter: Filter<Schema> = {}, options?: DeleteOneOptions): Promise<DeleteOneResult> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: DeleteOneCommand = {
@@ -783,7 +782,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    * the Data API and the client periodically exchange new chunks of documents.
    * It should be noted that the behavior of the cursor in the case documents
    * have been added/removed after the `find` was started depends on database
-   * internals and it is not guaranteed, nor excluded, that such "real-time"
+   * internals, and it is not guaranteed, nor excluded, that such "real-time"
    * changes in the data would be picked up by the cursor.
    *
    * @param filter - A filter to select the documents to find. If not provided, all documents will be returned.
@@ -793,7 +792,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @see StrictFilter
    */
-  find<GetSim extends boolean = false>(filter: Filter<Schema>, options?: FindOptions<Schema, GetSim>): FindCursor<FoundDoc<Schema, GetSim>, FoundDoc<Schema, GetSim>> {
+  find<GetSim extends boolean = false>(filter: Filter<Schema>, options?: FindOptions<GetSim>): FindCursor<FoundDoc<Schema, GetSim>, FoundDoc<Schema, GetSim>> {
     return new FindCursor(this.namespace, this._httpClient, filter as any, coalesceVectorSpecialsIntoSort(options)) as any;
   }
 
@@ -931,7 +930,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @see StrictFilter
    */
-  public async findOne<GetSim extends boolean = false>(filter: Filter<Schema>, options?: FindOneOptions<Schema, GetSim>): Promise<FoundDoc<Schema, GetSim> | null> {
+  public async findOne<GetSim extends boolean = false>(filter: Filter<Schema>, options?: FindOneOptions<GetSim>): Promise<FoundDoc<Schema, GetSim> | null> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneCommand = {
@@ -1059,7 +1058,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
   public async findOneAndReplace(
     filter: Filter<Schema>,
     replacement: NoId<Schema>,
-    options: FindOneAndReplaceOptions<Schema> & { includeResultMetadata: true },
+    options: FindOneAndReplaceOptions & { includeResultMetadata: true },
   ): Promise<ModifyResult<Schema>>
 
   /**
@@ -1103,10 +1102,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
   public async findOneAndReplace(
     filter: Filter<Schema>,
     replacement: NoId<Schema>,
-    options: FindOneAndReplaceOptions<Schema> & { includeResultMetadata?: false },
+    options: FindOneAndReplaceOptions & { includeResultMetadata?: false },
   ): Promise<WithId<Schema> | null>
 
-  public async findOneAndReplace(filter: Filter<Schema>, replacement: NoId<Schema>, options: FindOneAndReplaceOptions<Schema>): Promise<ModifyResult<Schema> | WithId<Schema> | null> {
+  public async findOneAndReplace(filter: Filter<Schema>, replacement: NoId<Schema>, options: FindOneAndReplaceOptions): Promise<ModifyResult<Schema> | WithId<Schema> | null> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneAndReplaceCommand = {
@@ -1175,7 +1174,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    */
   public async findOneAndDelete(
     filter: Filter<Schema>,
-    options: FindOneAndDeleteOptions<Schema> & { includeResultMetadata: true },
+    options: FindOneAndDeleteOptions & { includeResultMetadata: true },
   ): Promise<ModifyResult<Schema>>
 
   /**
@@ -1207,10 +1206,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    */
   public async findOneAndDelete(
     filter: Filter<Schema>,
-    options?: FindOneAndDeleteOptions<Schema> & { includeResultMetadata?: false },
+    options?: FindOneAndDeleteOptions & { includeResultMetadata?: false },
   ): Promise<WithId<Schema> | null>
 
-  public async findOneAndDelete(filter: Filter<Schema>, options?: FindOneAndDeleteOptions<Schema>): Promise<ModifyResult<Schema> | WithId<Schema> | null> {
+  public async findOneAndDelete(filter: Filter<Schema>, options?: FindOneAndDeleteOptions): Promise<ModifyResult<Schema> | WithId<Schema> | null> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneAndDeleteCommand = {
@@ -1277,7 +1276,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
   public async findOneAndUpdate(
     filter: Filter<Schema>,
     update: UpdateFilter<Schema>,
-    options: FindOneAndUpdateOptions<Schema> & { includeResultMetadata: true },
+    options: FindOneAndUpdateOptions & { includeResultMetadata: true },
   ): Promise<ModifyResult<Schema>>
 
   /**
@@ -1318,10 +1317,10 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
   public async findOneAndUpdate(
     filter: Filter<Schema>,
     update: UpdateFilter<Schema>,
-    options: FindOneAndUpdateOptions<Schema> & { includeResultMetadata?: false },
+    options: FindOneAndUpdateOptions & { includeResultMetadata?: false },
   ): Promise<WithId<Schema> | null>
 
-  public async findOneAndUpdate(filter: Filter<Schema>, update: UpdateFilter<Schema>, options: FindOneAndUpdateOptions<Schema>): Promise<ModifyResult<Schema> | WithId<Schema> | null> {
+  public async findOneAndUpdate(filter: Filter<Schema>, update: UpdateFilter<Schema>, options: FindOneAndUpdateOptions): Promise<ModifyResult<Schema> | WithId<Schema> | null> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneAndUpdateCommand = {

src/data-api/cursor.ts

@@ -17,8 +17,8 @@ import {
   FindOptions,
   InternalFindOptions,
   InternalGetMoreCommand,
-  StrictProjection,
-  StrictSort,
+  Projection,
+  Sort,
 } from '@/src/data-api/types';
 import { CursorAlreadyInitializedError, SomeDoc } from '@/src/data-api';
 import { DataApiHttpClient } from '@/src/api';
@@ -75,15 +75,15 @@ const enum CursorStatus {
 export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
   private readonly _namespace: string;
   private readonly _httpClient: DataApiHttpClient;
-  private readonly _options: FindOptions<SomeDoc, boolean>;
+  private readonly _options: FindOptions<boolean>;
   private _filter: Filter<SomeDoc>;
   private _mapping?: (doc: unknown) => T;
 
   private _buffer: TRaw[] = [];
   private _nextPageState?: string | null;
   private _state = CursorStatus.Uninitialized;
 
-  constructor(namespace: string, httpClient: DataApiHttpClient, filter: Filter<SomeDoc>, options?: FindOptions<SomeDoc, boolean>) {
+  constructor(namespace: string, httpClient: DataApiHttpClient, filter: Filter<SomeDoc>, options?: FindOptions<boolean>) {
     this._namespace = namespace;
     this._httpClient = httpClient;
     this._filter = filter;
@@ -141,7 +141,7 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    *
    * @return The cursor.
    */
-  sort(sort: StrictSort<TRaw>): FindCursor<T, TRaw> {
+  sort(sort: Sort): 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, RRaw extends SomeDoc = SomeDoc>(projection: StrictProjection<TRaw>): FindCursor<R, RRaw> {
+  project<R = any, RRaw extends SomeDoc = SomeDoc>(projection: Projection): FindCursor<R, RRaw> {
     this._assertUninitialized();
     this._options.projection = projection;
     return this as any;

src/data-api/types/collections/collections-common.ts

@@ -23,43 +23,21 @@ import { ToDotNotation } from '@/src/data-api/types/dot-notation';
  * @field dimension - The dimension of the vectors.
  * @field metric - The similarity metric to use for the vector search.
  */
-export type VectorOptions =
-  | ManualVectorOptions
-  | VectorizeOptions;
-
-/**
- * Represents the options for the vector search.
- *
- * **If not specified, the collection will not support vector search.**
- *
- * @field dimension - The dimension of the vectors.
- * @field metric - The similarity metric to use for the vector search.
- * @field service - Options related to the vectorization pipeline, to specify an embedding service.
- */
-export interface ManualVectorOptions {
+export interface VectorOptions {
   /**
    * The dimension of the vectors stored in the collection.
    */
-  dimension: number,
+  dimension?: number,
   /**
    * The similarity metric to use for the vector search.
    *
    * See [intro to vector databases](https://docs.datastax.com/en/astra/astra-db-vector/get-started/concepts.html#metrics) for more details.
    */
-  metric: 'cosine' | 'euclidean' | 'dot_product',
+  metric?: 'cosine' | 'euclidean' | 'dot_product',
   /**
    * @alpha
    */
-  service?: never,
-}
-
-/**
- * @alpha
- */
-export interface VectorizeOptions {
-  service: VectorizeServiceOptions,
-  dimension?: never,
-  metric?: never,
+  service?: VectorizeServiceOptions,
 }
 
 /**

src/data-api/types/common.ts

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { ObjectId, SomeDoc, UUID } from '@/src/data-api';
+import { ObjectId, SomeDoc, UUID, WithId } from '@/src/data-api';
 import type { ToDotNotation } from '@/src/data-api/types';
 
 export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId;
@@ -35,19 +35,19 @@ export type Projection = Record<string, 1 | 0 | true | false | Slice>;
  * @example
  * ```typescript
  * // Sort by name in ascending order, then by age in descending order
- * const sort1: StrictSort<SomeDoc> = {
+ * const sort1: Sort<SomeDoc> = {
  *   name: 1,
  *   age: -1,
  * }
  *
  * // Sort by vector distance
- * const sort2: StrictSort<SomeDoc> = {
+ * const sort2: Sort<SomeDoc> = {
  *   $vector: [0.23, 0.38, 0.27, 0.91, 0.21],
  * }
  * ```
  */
 export type StrictSort<Schema extends SomeDoc> =
-  | { [K in keyof ToDotNotation<Schema>]?: 1 | -1 }
+  | { [K in keyof ToDotNotation<WithId<Schema>>]?: 1 | -1 }
   | { $vector: { $meta: number[] } }
   | { $vector: number[] }
   | { $vectorize: string };
@@ -60,25 +60,25 @@ export type StrictSort<Schema extends SomeDoc> =
  * @example
  * ```typescript
  * // Include _id, name, and address.state
- * const projection1: StrictProjection<SomeDoc> = {
+ * const projection1: Projection<SomeDoc> = {
  *   _id: 1,
  *   name: 1,
  *   'address.state': 1,
  * }
  *
  * // Exclude the $vector
- * const projection2: StrictProjection<SomeDoc> = {
+ * const projection2: Projection<SomeDoc> = {
  *   $vector: 0,
  * }
  *
  * // Return array indices 2, 3, 4, and 5
- * const projection3: StrictProjection<SomeDoc> = {
+ * const projection3: Projection<SomeDoc> = {
  *   test_scores: { $slice: [2, 4] },
  * }
  * ```
  */
 export type StrictProjection<Schema extends SomeDoc> = {
-  [K in keyof ToDotNotation<Schema> | '_id']?: any[] extends (ToDotNotation<Schema> & { _id: any })[K]
+  [K in keyof ToDotNotation<WithId<Schema>>]?: any[] extends (ToDotNotation<WithId<Schema>>)[K]
     ? 1 | 0 | true | false | Slice
     : 1 | 0 | true | false;
 };

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

@@ -12,15 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { SomeDoc } from '@/src/data-api';
-import type { StrictSort } from '@/src/data-api/types';
+import type { Sort } from '@/src/data-api/types';
 import { WithTimeout } from '@/src/common/types';
 
 /** @internal */
 export interface DeleteOneCommand {
   deleteOne: {
     filter: Record<string, unknown>;
-    sort?: StrictSort<any>;
+    sort?: Sort;
   };
 }
 
@@ -32,7 +31,7 @@ export interface DeleteOneCommand {
  *
  * @see Collection.deleteOne
  */
-export interface DeleteOneOptions<Schema extends SomeDoc> extends WithTimeout {
+export interface DeleteOneOptions extends WithTimeout {
   /**
    * The order in which to apply the update if the filter selects multiple documents.
    *
@@ -41,7 +40,7 @@ export interface DeleteOneOptions<Schema extends SomeDoc> extends WithTimeout {
    * Defaults to `null`, where the order is not guaranteed.
    * @defaultValue null
    */
-  sort?: StrictSort<Schema>,
+  sort?: Sort,
   /**
    * An optional vector to use of the appropriate dimensionality to perform an ANN vector search on the collection
    * to find the closest matching document.

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

@@ -12,16 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { StrictProjection, StrictSort } from '@/src/data-api/types';
-import { SomeDoc } from '@/src/data-api';
+import type { Projection, Sort } from '@/src/data-api/types';
 import { WithTimeout } from '@/src/common/types';
 
 /** @internal */
 export interface FindOneAndDeleteCommand {
   findOneAndDelete: {
     filter?: Record<string, unknown>;
-    sort?: StrictSort<any>;
-    projection?: StrictProjection<any>;
+    sort?: Sort;
+    projection?: Projection;
   };
 }
 
@@ -35,7 +34,7 @@ export interface FindOneAndDeleteCommand {
  *
  * @see Collection.findOneAndDelete
  */
-export interface FindOneAndDeleteOptions<Schema extends SomeDoc> extends WithTimeout {
+export interface FindOneAndDeleteOptions extends WithTimeout {
   /**
    * The order in which to apply the update if the filter selects multiple documents.
    *
@@ -44,7 +43,7 @@ export interface FindOneAndDeleteOptions<Schema extends SomeDoc> extends WithTim
    * Defaults to `null`, where the order is not guaranteed.
    * @defaultValue null
    */
-  sort?: StrictSort<Schema>,
+  sort?: Sort,
   /**
    * An optional vector to use of the appropriate dimensionality to perform an ANN vector search on the collection
    * to find the closest matching document.
@@ -96,7 +95,7 @@ export interface FindOneAndDeleteOptions<Schema extends SomeDoc> extends WithTim
    * console.log(doc.age);
    * ```
    */
-  projection?: StrictProjection<Schema>,
+  projection?: Projection,
   /**
    * When true, returns alongside the document, an `ok` field with a value of 1 if the command executed successfully.
    *