feat(NODE-6893): Distinguish between command-level options and index-level options when creating indexes

src/collection.ts

@@ -56,12 +56,14 @@ import {
 import {
   CreateIndexesOperation,
   type CreateIndexesOptions,
+  type CreateIndexOptions,
   type DropIndexesOptions,
   DropIndexOperation,
   type IndexDescription,
   type IndexDescriptionCompact,
   type IndexDescriptionInfo,
   type IndexInformationOptions,
+  type IndexOptions,
   type IndexSpecification,
   type ListIndexesOptions
 } from './operations/indexes';
@@ -609,7 +611,7 @@ export class Collection<TSchema extends Document = Document> {
    * Creates an index on the db and collection collection.
    *
    * @param indexSpec - The field name or index specification to create an index for
-   * @param options - Optional settings for the command
+   * @param indexOptions - Optional settings for the command
    *
    * @example
    * ```ts
@@ -632,20 +634,55 @@ export class Collection<TSchema extends Document = Document> {
    * // Equivalent to { j: 1, k: -1, l: 2d }
    * await collection.createIndex(['j', ['k', -1], { l: '2d' }])
    * ```
+   * @deprecated Use the three parameter overload, which separates index options from
+   *   command options. This overload will be removed in a future major release.
+   */
+  createIndex(indexSpec: IndexSpecification, options?: CreateIndexesOptions): Promise<string>;
+
+  /**
+   * Creates an index on the db and collection collection.
+   *
+   * Options for the index itself are given in `indexOptions`, and options for the
+   * `createIndexes` command are given separately in `commandOptions`. Unknown fields in
+   * `indexOptions` are passed through to the server for validation rather than being dropped.
+   *
+   * @param keys - The field name or index specification to create an index for
+   * @param indexOptions - Settings for the index, or `undefined` if there are none
+   * @param commandOptions - Settings for the `createIndexes` command, or `undefined` if there are none
    */
+  createIndex(
+    keys: IndexSpecification,
+    indexOptions: IndexOptions | undefined,
+    commandOptions: CreateIndexOptions | undefined
+  ): Promise<string>;
+
   async createIndex(
     indexSpec: IndexSpecification,
-    options?: CreateIndexesOptions
+    indexOptions?: CreateIndexesOptions | IndexOptions,
+    commandOptions?: CreateIndexOptions
   ): Promise<string> {
-    const indexes = await executeOperation(
-      this.client,
-      CreateIndexesOperation.fromIndexSpecification(
-        this,
-        this.collectionName,
-        indexSpec,
-        resolveOptions(this, options)
-      )
-    );
+    // When commandOptions is provided the caller has separated the two kinds of options, so the
+    // index options are forwarded as-is and only the command options inherit from the parent.
+    // Otherwise indexOptions is both, and it inherits from the parent as it always has.
+    const operation =
+      commandOptions == null
+        ? CreateIndexesOperation.fromIndexSpecification(
+            this,
+            this.collectionName,
+            indexSpec,
+            /*allowUnknownIndexOptions=*/ false,
+            resolveOptions(this, indexOptions), // at this point indexOptions is the combined index and command options
+            undefined
+          )
+        : CreateIndexesOperation.fromIndexSpecification(
+            this,
+            this.collectionName,
+            indexSpec,
+            /*allowUnknownIndexOptions=*/ true,
+            indexOptions,
+            resolveOptions(this, commandOptions)
+          );
+    const indexes = await executeOperation(this.client, operation);
 
     return indexes[0];
   }
@@ -659,7 +696,7 @@ export class Collection<TSchema extends Document = Document> {
    * Index specifications are defined {@link https://www.mongodb.com/docs/manual/reference/command/createIndexes/| here}.
    *
    * @param indexSpecs - An array of index specifications to be created
-   * @param options - Optional settings for the command
+   * @param commandOptions - Optional settings for the `createIndexes` command
    *
    * @example
    * ```ts
@@ -681,17 +718,45 @@ export class Collection<TSchema extends Document = Document> {
    * ]);
    * ```
    */
+  createIndexes(
+    indexSpecs: IndexDescription[],
+    commandOptions?: CreateIndexesOptions
+  ): Promise<string[]>;
+
+  /**
+   * Creates multiple indexes in the collection, opting into "pass through" behavior for index
+   * options the driver does not recognise.
+   *
+   * @param indexSpecs - An array of index specifications to be created
+   * @param commandOptions - Optional settings for the `createIndexes` command
+   * @param allowUnknownIndexOptions - When `true`, index options the driver does not recognise are
+   *   sent to the server instead of being dropped, for the server to validate.
+   *
+   * @deprecated Used to opt into "pass through" behavior, where options will be validated by the
+   *   server rather than the driver. In a future release this overload will be removed and the
+   *   default behavior will change from `false` to `true`.
+   */
+  createIndexes(
+    indexSpecs: IndexDescription[],
+    commandOptions: CreateIndexesOptions | undefined,
+    allowUnknownIndexOptions: boolean
+  ): Promise<string[]>;
+
   async createIndexes(
     indexSpecs: IndexDescription[],
-    options?: CreateIndexesOptions
+    commandOptions?: CreateIndexesOptions,
+    // TODO(NODE-7868): Remove allowUnknownIndexOptions with a default behavior of true in a future major version release
+    allowUnknownIndexOptions = false
   ): Promise<string[]> {
     return await executeOperation(
       this.client,
       CreateIndexesOperation.fromIndexDescriptionArray(
         this,
         this.collectionName,
         indexSpecs,
-        resolveOptions(this, { ...options, maxTimeMS: undefined })
+        // TODO(NODE-7868): Remove allowUnknownIndexOptions with a default behavior of true in a future major version release
+        allowUnknownIndexOptions,
+        resolveOptions(this, { ...commandOptions, maxTimeMS: undefined })
       )
     );
   }

src/db.ts

@@ -454,7 +454,14 @@ export class Db {
   ): Promise<string> {
     const indexes = await executeOperation(
       this.client,
-      CreateIndexesOperation.fromIndexSpecification(this, name, indexSpec, options)
+      CreateIndexesOperation.fromIndexSpecification(
+        this,
+        name,
+        indexSpec,
+        /*allowUnknownIndexOptions=*/ false,
+        options ?? {},
+        undefined
+      )
     );
     return indexes[0];
   }

src/gridfs/upload.ts

@@ -272,12 +272,7 @@ async function checkChunksIndex(stream: GridFSBucketWriteStream): Promise<void>
     remainingTimeMS = stream.timeoutContext?.getRemainingTimeMSOrThrow(
       `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
     );
-    await stream.chunks.createIndex(index, {
-      ...stream.writeConcern,
-      background: true,
-      unique: true,
-      timeoutMS: remainingTimeMS
-    });
+    await stream.chunks.createIndex(index, { unique: true }, { timeoutMS: remainingTimeMS });
   }
 }
 
@@ -379,7 +374,7 @@ async function checkIndexes(stream: GridFSBucketWriteStream): Promise<void> {
       `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
     );
 
-    await stream.files.createIndex(index, { background: false, timeoutMS: remainingTimeMS });
+    await stream.files.createIndex(index, {}, { timeoutMS: remainingTimeMS });
   }
 
   await checkChunksIndex(stream);

src/index.ts

@@ -530,11 +530,13 @@ export type {
 export type { IndexInformationOptions } from './operations/indexes';
 export type {
   CreateIndexesOptions,
+  CreateIndexOptions,
   DropIndexesOptions,
   IndexDescription,
   IndexDescriptionCompact,
   IndexDescriptionInfo,
   IndexDirection,
+  IndexOptions,
   IndexSpecification,
   ListIndexesOptions
 } from './operations/indexes';

src/operations/create_collection.ts

@@ -207,7 +207,9 @@ export async function createCollections<TSchema extends Document>(
       db,
       name,
       { __safeContent__: 1 },
-      { session: options.session }
+      /*allowUnknownIndexOptions=*/ false,
+      { session: options.session },
+      undefined
     );
     await executeOperation(db.client, createIndexOp, timeoutContext);
   }