mongodb 6.9.0 → 6.10.0

package/src/operations/client_bulk_write/common.ts

@@ -27,25 +27,32 @@ export interface ClientBulkWriteOptions extends CommandOperationOptions {
 
 /** @public */
 export interface ClientWriteModel {
-  /** The namespace for the write. */
+  /**
+   * The namespace for the write.
+   *
+   * A namespace is a combination of the database name and the name of the collection: `<database-name>.<collection>`.
+   * All documents belong to a namespace.
+   *
+   * @see https://www.mongodb.com/docs/manual/reference/limits/#std-label-faq-dev-namespace
+   */
   namespace: string;
 }
 
 /** @public */
-export interface ClientInsertOneModel extends ClientWriteModel {
+export interface ClientInsertOneModel<TSchema> extends ClientWriteModel {
   name: 'insertOne';
   /** The document to insert. */
-  document: OptionalId<Document>;
+  document: OptionalId<TSchema>;
 }
 
 /** @public */
-export interface ClientDeleteOneModel extends ClientWriteModel {
+export interface ClientDeleteOneModel<TSchema> extends ClientWriteModel {
   name: 'deleteOne';
   /**
    * The filter used to determine if a document should be deleted.
    * For a deleteOne operation, the first match is removed.
    */
-  filter: Filter<Document>;
+  filter: Filter<TSchema>;
   /** Specifies a collation. */
   collation?: CollationOptions;
   /** The index to use. If specified, then the query system will only consider plans using the hinted index. */
@@ -53,13 +60,13 @@ export interface ClientDeleteOneModel extends ClientWriteModel {
 }
 
 /** @public */
-export interface ClientDeleteManyModel extends ClientWriteModel {
+export interface ClientDeleteManyModel<TSchema> extends ClientWriteModel {
   name: 'deleteMany';
   /**
    * The filter used to determine if a document should be deleted.
    * For a deleteMany operation, all matches are removed.
    */
-  filter: Filter<Document>;
+  filter: Filter<TSchema>;
   /** Specifies a collation. */
   collation?: CollationOptions;
   /** The index to use. If specified, then the query system will only consider plans using the hinted index. */
@@ -67,15 +74,15 @@ export interface ClientDeleteManyModel extends ClientWriteModel {
 }
 
 /** @public */
-export interface ClientReplaceOneModel extends ClientWriteModel {
+export interface ClientReplaceOneModel<TSchema> extends ClientWriteModel {
   name: 'replaceOne';
   /**
    * The filter used to determine if a document should be replaced.
    * For a replaceOne operation, the first match is replaced.
    */
-  filter: Filter<Document>;
+  filter: Filter<TSchema>;
   /** The document with which to replace the matched document. */
-  replacement: WithoutId<Document>;
+  replacement: WithoutId<TSchema>;
   /** Specifies a collation. */
   collation?: CollationOptions;
   /** The index to use. If specified, then the query system will only consider plans using the hinted index. */
@@ -85,19 +92,19 @@ export interface ClientReplaceOneModel extends ClientWriteModel {
 }
 
 /** @public */
-export interface ClientUpdateOneModel extends ClientWriteModel {
+export interface ClientUpdateOneModel<TSchema> extends ClientWriteModel {
   name: 'updateOne';
   /**
    * The filter used to determine if a document should be updated.
    * For an updateOne operation, the first match is updated.
    */
-  filter: Filter<Document>;
+  filter: Filter<TSchema>;
   /**
    * The modifications to apply. The value can be either:
    * UpdateFilter<Document> - A document that contains update operator expressions,
    * Document[] - an aggregation pipeline.
    */
-  update: UpdateFilter<Document> | Document[];
+  update: UpdateFilter<TSchema> | Document[];
   /** A set of filters specifying to which array elements an update should apply. */
   arrayFilters?: Document[];
   /** Specifies a collation. */
@@ -109,19 +116,19 @@ export interface ClientUpdateOneModel extends ClientWriteModel {
 }
 
 /** @public */
-export interface ClientUpdateManyModel extends ClientWriteModel {
+export interface ClientUpdateManyModel<TSchema> extends ClientWriteModel {
   name: 'updateMany';
   /**
    * The filter used to determine if a document should be updated.
    * For an updateMany operation, all matches are updated.
    */
-  filter: Filter<Document>;
+  filter: Filter<TSchema>;
   /**
    * The modifications to apply. The value can be either:
    * UpdateFilter<Document> - A document that contains update operator expressions,
    * Document[] - an aggregation pipeline.
    */
-  update: UpdateFilter<Document> | Document[];
+  update: UpdateFilter<TSchema> | Document[];
   /** A set of filters specifying to which array elements an update should apply. */
   arrayFilters?: Document[];
   /** Specifies a collation. */
@@ -137,10 +144,128 @@ export interface ClientUpdateManyModel extends ClientWriteModel {
  * to MongoClient#bulkWrite.
  * @public
  */
-export type AnyClientBulkWriteModel =
-  | ClientInsertOneModel
-  | ClientReplaceOneModel
-  | ClientUpdateOneModel
-  | ClientUpdateManyModel
-  | ClientDeleteOneModel
-  | ClientDeleteManyModel;
+export type AnyClientBulkWriteModel<TSchema extends Document> =
+  | ClientInsertOneModel<TSchema>
+  | ClientReplaceOneModel<TSchema>
+  | ClientUpdateOneModel<TSchema>
+  | ClientUpdateManyModel<TSchema>
+  | ClientDeleteOneModel<TSchema>
+  | ClientDeleteManyModel<TSchema>;
+
+/**
+ * A mapping of namespace strings to collections schemas.
+ * @public
+ *
+ * @example
+ * ```ts
+ * type MongoDBSchemas = {
+ *   'db.books': Book;
+ *   'db.authors': Author;
+ * }
+ *
+ * const model: ClientBulkWriteModel<MongoDBSchemas> = {
+ *   namespace: 'db.books'
+ *   name: 'insertOne',
+ *   document: { title: 'Practical MongoDB Aggregations', authorName: 3 } // error `authorName` cannot be number
+ * };
+ * ```
+ *
+ * The type of the `namespace` field narrows other parts of the BulkWriteModel to use the correct schema for type assertions.
+ *
+ */
+export type ClientBulkWriteModel<
+  SchemaMap extends Record<string, Document> = Record<string, Document>
+> = {
+  [Namespace in keyof SchemaMap]: AnyClientBulkWriteModel<SchemaMap[Namespace]> & {
+    namespace: Namespace;
+  };
+}[keyof SchemaMap];
+
+/** @public */
+export interface ClientBulkWriteResult {
+  /**
+   * Whether the bulk write was acknowledged.
+   */
+  readonly acknowledged: boolean;
+  /**
+   * The total number of documents inserted across all insert operations.
+   */
+  readonly insertedCount: number;
+  /**
+   * The total number of documents upserted across all update operations.
+   */
+  readonly upsertedCount: number;
+  /**
+   * The total number of documents matched across all update operations.
+   */
+  readonly matchedCount: number;
+  /**
+   * The total number of documents modified across all update operations.
+   */
+  readonly modifiedCount: number;
+  /**
+   * The total number of documents deleted across all delete operations.
+   */
+  readonly deletedCount: number;
+  /**
+   * The results of each individual insert operation that was successfully performed.
+   */
+  readonly insertResults?: ReadonlyMap<number, ClientInsertOneResult>;
+  /**
+   * The results of each individual update operation that was successfully performed.
+   */
+  readonly updateResults?: ReadonlyMap<number, ClientUpdateResult>;
+  /**
+   * The results of each individual delete operation that was successfully performed.
+   */
+  readonly deleteResults?: ReadonlyMap<number, ClientDeleteResult>;
+}
+
+/** @public */
+export interface ClientBulkWriteError {
+  code: number;
+  message: string;
+}
+
+/** @public */
+export interface ClientInsertOneResult {
+  /**
+   * The _id of the inserted document.
+   */
+  insertedId: any;
+}
+
+/** @public */
+export interface ClientUpdateResult {
+  /**
+   * The number of documents that matched the filter.
+   */
+  matchedCount: number;
+
+  /**
+   * The number of documents that were modified.
+   */
+  modifiedCount: number;
+
+  /**
+   * The _id field of the upserted document if an upsert occurred.
+   *
+   * It MUST be possible to discern between a BSON Null upserted ID value and this field being
+   * unset. If necessary, drivers MAY add a didUpsert boolean field to differentiate between
+   * these two cases.
+   */
+  upsertedId?: any;
+
+  /**
+   * Determines if the upsert did include an _id, which includes the case of the _id being null.
+   */
+  didUpsert: boolean;
+}
+
+/** @public */
+export interface ClientDeleteResult {
+  /**
+   * The number of documents that were deleted.
+   */
+  deletedCount: number;
+}

package/src/operations/client_bulk_write/executor.ts

@@ -0,0 +1,137 @@
+import { type Document } from '../../bson';
+import { ClientBulkWriteCursor } from '../../cursor/client_bulk_write_cursor';
+import {
+  MongoClientBulkWriteError,
+  MongoClientBulkWriteExecutionError,
+  MongoInvalidArgumentError,
+  MongoServerError
+} from '../../error';
+import { type MongoClient } from '../../mongo_client';
+import { WriteConcern } from '../../write_concern';
+import { executeOperation } from '../execute_operation';
+import { ClientBulkWriteOperation } from './client_bulk_write';
+import { ClientBulkWriteCommandBuilder } from './command_builder';
+import {
+  type AnyClientBulkWriteModel,
+  type ClientBulkWriteOptions,
+  type ClientBulkWriteResult
+} from './common';
+import { ClientBulkWriteResultsMerger } from './results_merger';
+
+/**
+ * Responsible for executing a client bulk write.
+ * @internal
+ */
+export class ClientBulkWriteExecutor {
+  private readonly client: MongoClient;
+  private readonly options: ClientBulkWriteOptions;
+  private readonly operations: ReadonlyArray<AnyClientBulkWriteModel<Document>>;
+
+  /**
+   * Instantiate the executor.
+   * @param client - The mongo client.
+   * @param operations - The user supplied bulk write models.
+   * @param options - The bulk write options.
+   */
+  constructor(
+    client: MongoClient,
+    operations: ReadonlyArray<AnyClientBulkWriteModel<Document>>,
+    options?: ClientBulkWriteOptions
+  ) {
+    if (operations.length === 0) {
+      throw new MongoClientBulkWriteExecutionError('No client bulk write models were provided.');
+    }
+
+    this.client = client;
+    this.operations = operations;
+    this.options = {
+      ordered: true,
+      bypassDocumentValidation: false,
+      verboseResults: false,
+      ...options
+    };
+
+    // If no write concern was provided, we inherit one from the client.
+    if (!this.options.writeConcern) {
+      this.options.writeConcern = WriteConcern.fromOptions(this.client.options);
+    }
+
+    if (this.options.writeConcern?.w === 0) {
+      if (this.options.verboseResults) {
+        throw new MongoInvalidArgumentError(
+          'Cannot request unacknowledged write concern and verbose results'
+        );
+      }
+
+      if (this.options.ordered) {
+        throw new MongoInvalidArgumentError(
+          'Cannot request unacknowledged write concern and ordered writes'
+        );
+      }
+    }
+  }
+
+  /**
+   * Execute the client bulk write. Will split commands into batches and exhaust the cursors
+   * for each, then merge the results into one.
+   * @returns The result.
+   */
+  async execute(): Promise<ClientBulkWriteResult> {
+    // The command builder will take the user provided models and potential split the batch
+    // into multiple commands due to size.
+    const pkFactory = this.client.s.options.pkFactory;
+    const commandBuilder = new ClientBulkWriteCommandBuilder(
+      this.operations,
+      this.options,
+      pkFactory
+    );
+    // Unacknowledged writes need to execute all batches and return { ok: 1}
+    if (this.options.writeConcern?.w === 0) {
+      while (commandBuilder.hasNextBatch()) {
+        const operation = new ClientBulkWriteOperation(commandBuilder, this.options);
+        await executeOperation(this.client, operation);
+      }
+      return ClientBulkWriteResultsMerger.unacknowledged();
+    } else {
+      const resultsMerger = new ClientBulkWriteResultsMerger(this.options);
+      // For each command will will create and exhaust a cursor for the results.
+      while (commandBuilder.hasNextBatch()) {
+        const cursor = new ClientBulkWriteCursor(this.client, commandBuilder, this.options);
+        try {
+          await resultsMerger.merge(cursor);
+        } catch (error) {
+          // Write concern errors are recorded in the writeConcernErrors field on MongoClientBulkWriteError.
+          // When a write concern error is encountered, it should not terminate execution of the bulk write
+          // for either ordered or unordered bulk writes. However, drivers MUST throw an exception at the end
+          // of execution if any write concern errors were observed.
+          if (error instanceof MongoServerError && !(error instanceof MongoClientBulkWriteError)) {
+            // Server side errors need to be wrapped inside a MongoClientBulkWriteError, where the root
+            // cause is the error property and a partial result is to be included.
+            const bulkWriteError = new MongoClientBulkWriteError({
+              message: 'Mongo client bulk write encountered an error during execution'
+            });
+            bulkWriteError.cause = error;
+            bulkWriteError.partialResult = resultsMerger.bulkWriteResult;
+            throw bulkWriteError;
+          } else {
+            // Client side errors are just thrown.
+            throw error;
+          }
+        }
+      }
+
+      // If we have write concern errors or unordered write errors at the end we throw.
+      if (resultsMerger.writeConcernErrors.length > 0 || resultsMerger.writeErrors.size > 0) {
+        const error = new MongoClientBulkWriteError({
+          message: 'Mongo client bulk write encountered errors during execution.'
+        });
+        error.writeConcernErrors = resultsMerger.writeConcernErrors;
+        error.writeErrors = resultsMerger.writeErrors;
+        error.partialResult = resultsMerger.bulkWriteResult;
+        throw error;
+      }
+
+      return resultsMerger.bulkWriteResult;
+    }
+  }
+}

package/src/operations/client_bulk_write/results_merger.ts

@@ -0,0 +1,260 @@
+import { MongoWriteConcernError } from '../..';
+import { type Document } from '../../bson';
+import { type ClientBulkWriteCursor } from '../../cursor/client_bulk_write_cursor';
+import { MongoClientBulkWriteError } from '../../error';
+import {
+  type ClientBulkWriteError,
+  type ClientBulkWriteOptions,
+  type ClientBulkWriteResult,
+  type ClientDeleteResult,
+  type ClientInsertOneResult,
+  type ClientUpdateResult
+} from './common';
+
+/**
+ * Unacknowledged bulk writes are always the same.
+ */
+const UNACKNOWLEDGED = {
+  acknowledged: false,
+  insertedCount: 0,
+  upsertedCount: 0,
+  matchedCount: 0,
+  modifiedCount: 0,
+  deletedCount: 0,
+  insertResults: undefined,
+  updateResults: undefined,
+  deleteResults: undefined
+};
+
+interface ClientBulkWriteResultAccumulation {
+  /**
+   * Whether the bulk write was acknowledged.
+   */
+  acknowledged: boolean;
+  /**
+   * The total number of documents inserted across all insert operations.
+   */
+  insertedCount: number;
+  /**
+   * The total number of documents upserted across all update operations.
+   */
+  upsertedCount: number;
+  /**
+   * The total number of documents matched across all update operations.
+   */
+  matchedCount: number;
+  /**
+   * The total number of documents modified across all update operations.
+   */
+  modifiedCount: number;
+  /**
+   * The total number of documents deleted across all delete operations.
+   */
+  deletedCount: number;
+  /**
+   * The results of each individual insert operation that was successfully performed.
+   */
+  insertResults?: Map<number, ClientInsertOneResult>;
+  /**
+   * The results of each individual update operation that was successfully performed.
+   */
+  updateResults?: Map<number, ClientUpdateResult>;
+  /**
+   * The results of each individual delete operation that was successfully performed.
+   */
+  deleteResults?: Map<number, ClientDeleteResult>;
+}
+
+/**
+ * Merges client bulk write cursor responses together into a single result.
+ * @internal
+ */
+export class ClientBulkWriteResultsMerger {
+  private result: ClientBulkWriteResultAccumulation;
+  private options: ClientBulkWriteOptions;
+  private currentBatchOffset: number;
+  writeConcernErrors: Document[];
+  writeErrors: Map<number, ClientBulkWriteError>;
+
+  /**
+   * @returns The standard unacknowledged bulk write result.
+   */
+  static unacknowledged(): ClientBulkWriteResult {
+    return UNACKNOWLEDGED;
+  }
+
+  /**
+   * Instantiate the merger.
+   * @param options - The options.
+   */
+  constructor(options: ClientBulkWriteOptions) {
+    this.options = options;
+    this.currentBatchOffset = 0;
+    this.writeConcernErrors = [];
+    this.writeErrors = new Map();
+    this.result = {
+      acknowledged: true,
+      insertedCount: 0,
+      upsertedCount: 0,
+      matchedCount: 0,
+      modifiedCount: 0,
+      deletedCount: 0,
+      insertResults: undefined,
+      updateResults: undefined,
+      deleteResults: undefined
+    };
+
+    if (options.verboseResults) {
+      this.result.insertResults = new Map<number, ClientInsertOneResult>();
+      this.result.updateResults = new Map<number, ClientUpdateResult>();
+      this.result.deleteResults = new Map<number, ClientDeleteResult>();
+    }
+  }
+
+  /**
+   * Get the bulk write result object.
+   */
+  get bulkWriteResult(): ClientBulkWriteResult {
+    return {
+      acknowledged: this.result.acknowledged,
+      insertedCount: this.result.insertedCount,
+      upsertedCount: this.result.upsertedCount,
+      matchedCount: this.result.matchedCount,
+      modifiedCount: this.result.modifiedCount,
+      deletedCount: this.result.deletedCount,
+      insertResults: this.result.insertResults,
+      updateResults: this.result.updateResults,
+      deleteResults: this.result.deleteResults
+    };
+  }
+
+  /**
+   * Merge the results in the cursor to the existing result.
+   * @param currentBatchOffset - The offset index to the original models.
+   * @param response - The cursor response.
+   * @param documents - The documents in the cursor.
+   * @returns The current result.
+   */
+  async merge(cursor: ClientBulkWriteCursor): Promise<ClientBulkWriteResult> {
+    let writeConcernErrorResult;
+    try {
+      for await (const document of cursor) {
+        // Only add to maps if ok: 1
+        if (document.ok === 1) {
+          if (this.options.verboseResults) {
+            this.processDocument(cursor, document);
+          }
+        } else {
+          // If an individual write error is encountered during an ordered bulk write, drivers MUST
+          // record the error in writeErrors and immediately throw the exception. Otherwise, drivers
+          // MUST continue to iterate the results cursor and execute any further bulkWrite batches.
+          if (this.options.ordered) {
+            const error = new MongoClientBulkWriteError({
+              message: 'Mongo client ordered bulk write encountered a write error.'
+            });
+            error.writeErrors.set(document.idx + this.currentBatchOffset, {
+              code: document.code,
+              message: document.errmsg
+            });
+            error.partialResult = this.result;
+            throw error;
+          } else {
+            this.writeErrors.set(document.idx + this.currentBatchOffset, {
+              code: document.code,
+              message: document.errmsg
+            });
+          }
+        }
+      }
+    } catch (error) {
+      if (error instanceof MongoWriteConcernError) {
+        const result = error.result;
+        writeConcernErrorResult = {
+          insertedCount: result.nInserted,
+          upsertedCount: result.nUpserted,
+          matchedCount: result.nMatched,
+          modifiedCount: result.nModified,
+          deletedCount: result.nDeleted,
+          writeConcernError: result.writeConcernError
+        };
+        if (this.options.verboseResults && result.cursor.firstBatch) {
+          for (const document of result.cursor.firstBatch) {
+            if (document.ok === 1) {
+              this.processDocument(cursor, document);
+            }
+          }
+        }
+      } else {
+        throw error;
+      }
+    } finally {
+      // Update the counts from the cursor response.
+      if (cursor.response) {
+        const response = cursor.response;
+        this.incrementCounts(response);
+      }
+
+      // Increment the batch offset.
+      this.currentBatchOffset += cursor.operations.length;
+    }
+
+    // If we have write concern errors ensure they are added.
+    if (writeConcernErrorResult) {
+      const writeConcernError = writeConcernErrorResult.writeConcernError as Document;
+      this.incrementCounts(writeConcernErrorResult);
+      this.writeConcernErrors.push({
+        code: writeConcernError.code,
+        message: writeConcernError.errmsg
+      });
+    }
+
+    return this.result;
+  }
+
+  /**
+   * Process an individual document in the results.
+   * @param cursor - The cursor.
+   * @param document - The document to process.
+   */
+  private processDocument(cursor: ClientBulkWriteCursor, document: Document) {
+    // Get the corresponding operation from the command.
+    const operation = cursor.operations[document.idx];
+    // Handle insert results.
+    if ('insert' in operation) {
+      this.result.insertResults?.set(document.idx + this.currentBatchOffset, {
+        insertedId: operation.document._id
+      });
+    }
+    // Handle update results.
+    if ('update' in operation) {
+      const result: ClientUpdateResult = {
+        matchedCount: document.n,
+        modifiedCount: document.nModified ?? 0,
+        // Check if the bulk did actually upsert.
+        didUpsert: document.upserted != null
+      };
+      if (document.upserted) {
+        result.upsertedId = document.upserted._id;
+      }
+      this.result.updateResults?.set(document.idx + this.currentBatchOffset, result);
+    }
+    // Handle delete results.
+    if ('delete' in operation) {
+      this.result.deleteResults?.set(document.idx + this.currentBatchOffset, {
+        deletedCount: document.n
+      });
+    }
+  }
+
+  /**
+   * Increment the result counts.
+   * @param document - The document with the results.
+   */
+  private incrementCounts(document: Document) {
+    this.result.insertedCount += document.insertedCount;
+    this.result.upsertedCount += document.upsertedCount;
+    this.result.matchedCount += document.matchedCount;
+    this.result.modifiedCount += document.modifiedCount;
+    this.result.deletedCount += document.deletedCount;
+  }
+}

package/src/operations/execute_operation.ts

@@ -230,6 +230,10 @@ async function tryOperation<
         });
       }
 
+      if (operation.hasAspect(Aspect.COMMAND_BATCHING) && !operation.canRetryWrite) {
+        throw previousOperationError;
+      }
+
       if (hasWriteAspect && !isRetryableWriteError(previousOperationError))
         throw previousOperationError;
 
@@ -260,6 +264,10 @@ async function tryOperation<
     }
 
     try {
+      // If tries > 0 and we are command batching we need to reset the batch.
+      if (tries > 0 && operation.hasAspect(Aspect.COMMAND_BATCHING)) {
+        operation.resetBatch();
+      }
       return await operation.execute(server, session);
     } catch (operationError) {
       if (!(operationError instanceof MongoError)) throw operationError;

package/src/operations/find.ts

@@ -1,6 +1,7 @@
 import type { Document } from '../bson';
 import { CursorResponse, ExplainedCursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError } from '../error';
+import { type ExplainOptions } from '../explain';
 import { ReadConcern } from '../read_concern';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
@@ -15,7 +16,7 @@ import { Aspect, defineAspects, type Hint } from './operation';
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface FindOptions<TSchema extends Document = Document>
-  extends Omit<CommandOperationOptions, 'writeConcern'> {
+  extends Omit<CommandOperationOptions, 'writeConcern' | 'explain'> {
   /** Sets the limit of documents returned in the query. */
   limit?: number;
   /** Set to sort the documents coming back from the query. Array of indexes, `[['a', 1]]` etc. */
@@ -63,6 +64,12 @@ export interface FindOptions<TSchema extends Document = Document>
    * @deprecated Starting from MongoDB 4.4 this flag is not needed and will be ignored.
    */
   oplogReplay?: boolean;
+
+  /**
+   * Specifies the verbosity mode for the explain output.
+   * @deprecated This API is deprecated in favor of `collection.find().explain()`.
+   */
+  explain?: ExplainOptions['explain'];
 }
 
 /** @internal */