mongodb 6.9.0-dev.20240917.sha.20396e1b → 6.9.0-dev.20240926.sha.3d3da407

package/src/index.ts

@@ -44,6 +44,7 @@ export {
   MongoAWSError,
   MongoAzureError,
   MongoBatchReExecutionError,
+  MongoBulkWriteCursorError,
   MongoChangeStreamError,
   MongoCompatibilityError,
   MongoCursorExhaustedError,
@@ -473,6 +474,21 @@ export type {
   AggregateOptions,
   DB_AGGREGATE_COLLECTION
 } from './operations/aggregate';
+export type {
+  AnyClientBulkWriteModel,
+  ClientBulkWriteOptions,
+  ClientBulkWriteResult,
+  ClientDeleteManyModel,
+  ClientDeleteOneModel,
+  ClientDeleteResult,
+  ClientInsertOneModel,
+  ClientInsertOneResult,
+  ClientReplaceOneModel,
+  ClientUpdateManyModel,
+  ClientUpdateOneModel,
+  ClientUpdateResult,
+  ClientWriteModel
+} from './operations/client_bulk_write/common';
 export type {
   CollationOptions,
   CommandOperation,

package/src/mongo_client.ts

@@ -30,6 +30,12 @@ import {
   SeverityLevel
 } from './mongo_logger';
 import { TypedEventEmitter } from './mongo_types';
+import {
+  type AnyClientBulkWriteModel,
+  type ClientBulkWriteOptions,
+  type ClientBulkWriteResult
+} from './operations/client_bulk_write/common';
+import { ClientBulkWriteExecutor } from './operations/client_bulk_write/executor';
 import { executeOperation } from './operations/execute_operation';
 import { RunAdminCommandOperation } from './operations/run_command';
 import type { ReadConcern, ReadConcernLevel, ReadConcernLike } from './read_concern';
@@ -477,6 +483,19 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
     return this.s.bsonOptions;
   }
 
+  /**
+   * Executes a client bulk write operation, available on server 8.0+.
+   * @param models - The client bulk write models.
+   * @param options - The client bulk write options.
+   * @returns A ClientBulkWriteResult for acknowledged writes and ok: 1 for unacknowledged writes.
+   */
+  async bulkWrite(
+    models: AnyClientBulkWriteModel[],
+    options?: ClientBulkWriteOptions
+  ): Promise<ClientBulkWriteResult | { ok: 1 }> {
+    return await new ClientBulkWriteExecutor(this, models, options).execute();
+  }
+
   /**
    * Connect to MongoDB using a url
    *

package/src/operations/client_bulk_write/client_bulk_write.ts

@@ -0,0 +1,45 @@
+import { type Document } from 'bson';
+
+import { ClientBulkWriteCursorResponse } from '../../cmap/wire_protocol/responses';
+import type { Server } from '../../sdam/server';
+import type { ClientSession } from '../../sessions';
+import { MongoDBNamespace } from '../../utils';
+import { CommandOperation } from '../command';
+import { Aspect, defineAspects } from '../operation';
+import { type ClientBulkWriteOptions } from './common';
+
+/**
+ * Executes a single client bulk write operation within a potential batch.
+ * @internal
+ */
+export class ClientBulkWriteOperation extends CommandOperation<ClientBulkWriteCursorResponse> {
+  command: Document;
+  override options: ClientBulkWriteOptions;
+
+  override get commandName() {
+    return 'bulkWrite' as const;
+  }
+
+  constructor(command: Document, options: ClientBulkWriteOptions) {
+    super(undefined, options);
+    this.command = command;
+    this.options = options;
+    this.ns = new MongoDBNamespace('admin', '$cmd');
+  }
+
+  /**
+   * Execute the command. Superclass will handle write concern, etc.
+   * @param server - The server.
+   * @param session - The session.
+   * @returns The response.
+   */
+  override async execute(
+    server: Server,
+    session: ClientSession | undefined
+  ): Promise<ClientBulkWriteCursorResponse> {
+    return await super.executeCommand(server, session, this.command, ClientBulkWriteCursorResponse);
+  }
+}
+
+// Skipping the collation as it goes on the individual ops.
+defineAspects(ClientBulkWriteOperation, [Aspect.WRITE_OPERATION, Aspect.SKIP_COLLATION]);

package/src/operations/client_bulk_write/command_builder.ts

@@ -1,6 +1,8 @@
 import { type Document } from '../../bson';
 import { DocumentSequence } from '../../cmap/commands';
+import { type PkFactory } from '../../mongo_client';
 import type { Filter, OptionalId, UpdateFilter, WithoutId } from '../../mongo_types';
+import { DEFAULT_PK_FACTORY } from '../../utils';
 import { type CollationOptions } from '../command';
 import { type Hint } from '../operation';
 import type {
@@ -23,20 +25,27 @@ export interface ClientBulkWriteCommand {
   nsInfo: DocumentSequence;
   bypassDocumentValidation?: boolean;
   let?: Document;
+  comment?: any;
 }
 
 /** @internal */
 export class ClientBulkWriteCommandBuilder {
   models: AnyClientBulkWriteModel[];
   options: ClientBulkWriteOptions;
+  pkFactory: PkFactory;
 
   /**
    * Create the command builder.
    * @param models - The client write models.
    */
-  constructor(models: AnyClientBulkWriteModel[], options: ClientBulkWriteOptions) {
+  constructor(
+    models: AnyClientBulkWriteModel[],
+    options: ClientBulkWriteOptions,
+    pkFactory?: PkFactory
+  ) {
     this.models = models;
     this.options = options;
+    this.pkFactory = pkFactory ?? DEFAULT_PK_FACTORY;
   }
 
   /**
@@ -62,10 +71,10 @@ export class ClientBulkWriteCommandBuilder {
       const ns = model.namespace;
       const index = namespaces.get(ns);
       if (index != null) {
-        operations.push(buildOperation(model, index));
+        operations.push(buildOperation(model, index, this.pkFactory));
       } else {
         namespaces.set(ns, currentNamespaceIndex);
-        operations.push(buildOperation(model, currentNamespaceIndex));
+        operations.push(buildOperation(model, currentNamespaceIndex, this.pkFactory));
         currentNamespaceIndex++;
       }
     }
@@ -88,6 +97,12 @@ export class ClientBulkWriteCommandBuilder {
     if (this.options.let) {
       command.let = this.options.let;
     }
+
+    // we check for undefined specifically here to allow falsy values
+    // eslint-disable-next-line no-restricted-syntax
+    if (this.options.comment !== undefined) {
+      command.comment = this.options.comment;
+    }
     return [command];
   }
 }
@@ -106,12 +121,14 @@ interface ClientInsertOperation {
  */
 export const buildInsertOneOperation = (
   model: ClientInsertOneModel,
-  index: number
+  index: number,
+  pkFactory: PkFactory
 ): ClientInsertOperation => {
   const document: ClientInsertOperation = {
     insert: index,
     document: model.document
   };
+  document.document._id = model.document._id ?? pkFactory.createPk();
   return document;
 };
 
@@ -175,6 +192,7 @@ export interface ClientUpdateOperation {
   hint?: Hint;
   upsert?: boolean;
   arrayFilters?: Document[];
+  collation?: CollationOptions;
 }
 
 /**
@@ -226,6 +244,9 @@ function createUpdateOperation(
   if (model.arrayFilters) {
     document.arrayFilters = model.arrayFilters;
   }
+  if (model.collation) {
+    document.collation = model.collation;
+  }
   return document;
 }
 
@@ -237,6 +258,7 @@ export interface ClientReplaceOneOperation {
   updateMods: WithoutId<Document>;
   hint?: Hint;
   upsert?: boolean;
+  collation?: CollationOptions;
 }
 
 /**
@@ -261,14 +283,21 @@ export const buildReplaceOneOperation = (
   if (model.upsert) {
     document.upsert = model.upsert;
   }
+  if (model.collation) {
+    document.collation = model.collation;
+  }
   return document;
 };
 
 /** @internal */
-export function buildOperation(model: AnyClientBulkWriteModel, index: number): Document {
+export function buildOperation(
+  model: AnyClientBulkWriteModel,
+  index: number,
+  pkFactory: PkFactory
+): Document {
   switch (model.name) {
     case 'insertOne':
-      return buildInsertOneOperation(model, index);
+      return buildInsertOneOperation(model, index, pkFactory);
     case 'deleteOne':
       return buildDeleteOneOperation(model, index);
     case 'deleteMany':

package/src/operations/client_bulk_write/common.ts

@@ -144,3 +144,82 @@ export type AnyClientBulkWriteModel =
   | ClientUpdateManyModel
   | ClientDeleteOneModel
   | ClientDeleteManyModel;
+
+/** @public */
+export interface ClientBulkWriteResult {
+  /**
+   * 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>;
+}
+
+/** @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,99 @@
+import { type Document } from 'bson';
+
+import { ClientBulkWriteCursor } from '../../cursor/client_bulk_write_cursor';
+import { type MongoClient } from '../../mongo_client';
+import { WriteConcern } from '../../write_concern';
+import { executeOperation } from '../execute_operation';
+import { ClientBulkWriteOperation } from './client_bulk_write';
+import { type ClientBulkWriteCommand, 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 {
+  client: MongoClient;
+  options: ClientBulkWriteOptions;
+  operations: AnyClientBulkWriteModel[];
+
+  /**
+   * 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: AnyClientBulkWriteModel[],
+    options?: ClientBulkWriteOptions
+  ) {
+    this.client = client;
+    this.operations = operations;
+    this.options = { ...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);
+    }
+  }
+
+  /**
+   * 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 | { ok: 1 }> {
+    // 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
+    );
+    const commands = commandBuilder.buildCommands();
+    if (this.options.writeConcern?.w === 0) {
+      return await executeUnacknowledged(this.client, this.options, commands);
+    }
+    return await executeAcknowledged(this.client, this.options, commands);
+  }
+}
+
+/**
+ * Execute an acknowledged bulk write.
+ */
+async function executeAcknowledged(
+  client: MongoClient,
+  options: ClientBulkWriteOptions,
+  commands: ClientBulkWriteCommand[]
+): Promise<ClientBulkWriteResult> {
+  const resultsMerger = new ClientBulkWriteResultsMerger(options);
+  // For each command will will create and exhaust a cursor for the results.
+  for (const command of commands) {
+    const cursor = new ClientBulkWriteCursor(client, command, options);
+    const docs = await cursor.toArray();
+    resultsMerger.merge(command.ops.documents, cursor.response, docs);
+  }
+  return resultsMerger.result;
+}
+
+/**
+ * Execute an unacknowledged bulk write.
+ */
+async function executeUnacknowledged(
+  client: MongoClient,
+  options: ClientBulkWriteOptions,
+  commands: Document[]
+): Promise<{ ok: 1 }> {
+  for (const command of commands) {
+    const operation = new ClientBulkWriteOperation(command, options);
+    await executeOperation(client, operation);
+  }
+  return { ok: 1 };
+}

package/src/operations/client_bulk_write/results_merger.ts

@@ -0,0 +1,95 @@
+import { type Document } from '../../bson';
+import { type ClientBulkWriteCursorResponse } from '../../cmap/wire_protocol/responses';
+import {
+  type ClientBulkWriteOptions,
+  type ClientBulkWriteResult,
+  type ClientDeleteResult,
+  type ClientInsertOneResult,
+  type ClientUpdateResult
+} from './common';
+
+/**
+ * Merges client bulk write cursor responses together into a single result.
+ * @internal
+ */
+export class ClientBulkWriteResultsMerger {
+  result: ClientBulkWriteResult;
+  options: ClientBulkWriteOptions;
+
+  /**
+   * Instantiate the merger.
+   * @param options - The options.
+   */
+  constructor(options: ClientBulkWriteOptions) {
+    this.options = options;
+    this.result = {
+      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>();
+    }
+  }
+
+  /**
+   * Merge the results in the cursor to the existing result.
+   * @param response - The cursor response.
+   * @param documents - The documents in the cursor.
+   * @returns The current result.
+   */
+  merge(
+    operations: Document[],
+    response: ClientBulkWriteCursorResponse,
+    documents: Document[]
+  ): ClientBulkWriteResult {
+    // Update the counts from the cursor response.
+    this.result.insertedCount += response.insertedCount;
+    this.result.upsertedCount += response.upsertedCount;
+    this.result.matchedCount += response.matchedCount;
+    this.result.modifiedCount += response.modifiedCount;
+    this.result.deletedCount += response.deletedCount;
+
+    if (this.options.verboseResults) {
+      // Iterate all the documents in the cursor and update the result.
+      for (const document of documents) {
+        // Only add to maps if ok: 1
+        if (document.ok === 1) {
+          // Get the corresponding operation from the command.
+          const operation = operations[document.idx];
+          // Handle insert results.
+          if ('insert' in operation) {
+            this.result.insertResults?.set(document.idx, { 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, result);
+          }
+          // Handle delete results.
+          if ('delete' in operation) {
+            this.result.deleteResults?.set(document.idx, { deletedCount: document.n });
+          }
+        }
+      }
+    }
+
+    return this.result;
+  }
+}

package/src/write_concern.ts

@@ -58,7 +58,10 @@ interface CommandWriteConcernOptions {
  * @see https://www.mongodb.com/docs/manual/reference/write-concern/
  */
 export class WriteConcern {
-  /** Request acknowledgment that the write operation has propagated to a specified number of mongod instances or to mongod instances with specified tags. */
+  /**
+   * Request acknowledgment that the write operation has propagated to a specified number of mongod instances or to mongod instances with specified tags.
+   * If w is 0 and is set on a write operation, the server will not send a response.
+   */
   readonly w?: W;
   /** Request acknowledgment that the write operation has been written to the on-disk journal */
   readonly journal?: boolean;