mongodb 6.9.0 → 6.10.0

package/src/cmap/wire_protocol/responses.ts

@@ -1,9 +1,8 @@
-import { type DeserializeOptions } from 'bson';
-
 import {
   type BSONElement,
   type BSONSerializeOptions,
   BSONType,
+  type DeserializeOptions,
   type Document,
   Long,
   parseToElementsToArray,
@@ -329,3 +328,33 @@ export class ExplainedCursorResponse extends CursorResponse {
     return this.toObject(options);
   }
 }
+
+/**
+ * Client bulk writes have some extra metadata at the top level that needs to be
+ * included in the result returned to the user.
+ */
+export class ClientBulkWriteCursorResponse extends CursorResponse {
+  get insertedCount() {
+    return this.get('nInserted', BSONType.int, true);
+  }
+
+  get upsertedCount() {
+    return this.get('nUpserted', BSONType.int, true);
+  }
+
+  get matchedCount() {
+    return this.get('nMatched', BSONType.int, true);
+  }
+
+  get modifiedCount() {
+    return this.get('nModified', BSONType.int, true);
+  }
+
+  get deletedCount() {
+    return this.get('nDeleted', BSONType.int, true);
+  }
+
+  get writeConcernError() {
+    return this.get('writeConcernError', BSONType.object, false);
+  }
+}

package/src/connection_string.ts

@@ -34,11 +34,11 @@ import { ReadPreference, type ReadPreferenceMode } from './read_preference';
 import { ServerMonitoringMode } from './sdam/monitor';
 import type { TagSet } from './sdam/server_description';
 import {
+  checkParentDomainMatch,
   DEFAULT_PK_FACTORY,
   emitWarning,
   HostAddress,
   isRecord,
-  matchesParentDomain,
   parseInteger,
   setDifference,
   squashError
@@ -64,11 +64,6 @@ export async function resolveSRVRecord(options: MongoOptions): Promise<HostAddre
     throw new MongoAPIError('Option "srvHost" must not be empty');
   }
 
-  if (options.srvHost.split('.').length < 3) {
-    // TODO(NODE-3484): Replace with MongoConnectionStringError
-    throw new MongoAPIError('URI must include hostname, domain name, and tld');
-  }
-
   // Asynchronously start TXT resolution so that we do not have to wait until
   // the SRV record is resolved before starting a second DNS query.
   const lookupAddress = options.srvHost;
@@ -86,9 +81,7 @@ export async function resolveSRVRecord(options: MongoOptions): Promise<HostAddre
   }
 
   for (const { name } of addresses) {
-    if (!matchesParentDomain(name, lookupAddress)) {
-      throw new MongoAPIError('Server record does not share hostname with parent URI');
-    }
+    checkParentDomainMatch(name, lookupAddress);
   }
 
   const hostAddresses = addresses.map(r => HostAddress.fromString(`${r.name}:${r.port ?? 27017}`));

package/src/cursor/aggregation_cursor.ts

@@ -1,5 +1,5 @@
 import type { Document } from '../bson';
-import type { ExplainVerbosityLike } from '../explain';
+import type { ExplainCommandOptions, ExplainVerbosityLike } from '../explain';
 import type { MongoClient } from '../mongo_client';
 import { AggregateOperation, type AggregateOptions } from '../operations/aggregate';
 import { executeOperation } from '../operations/execute_operation';
@@ -66,7 +66,7 @@ export class AggregationCursor<TSchema = any> extends AbstractCursor<TSchema> {
   }
 
   /** Execute the explain for the cursor */
-  async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
+  async explain(verbosity?: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document> {
     return (
       await executeOperation(
         this.client,

package/src/cursor/client_bulk_write_cursor.ts

@@ -0,0 +1,79 @@
+import { type Document } from '../bson';
+import { type ClientBulkWriteCursorResponse } from '../cmap/wire_protocol/responses';
+import type { MongoClient } from '../mongo_client';
+import { ClientBulkWriteOperation } from '../operations/client_bulk_write/client_bulk_write';
+import { type ClientBulkWriteCommandBuilder } from '../operations/client_bulk_write/command_builder';
+import { type ClientBulkWriteOptions } from '../operations/client_bulk_write/common';
+import { executeOperation } from '../operations/execute_operation';
+import type { ClientSession } from '../sessions';
+import { mergeOptions, MongoDBNamespace } from '../utils';
+import {
+  AbstractCursor,
+  type AbstractCursorOptions,
+  type InitialCursorResponse
+} from './abstract_cursor';
+
+/** @public */
+export interface ClientBulkWriteCursorOptions
+  extends Omit<AbstractCursorOptions, 'maxAwaitTimeMS' | 'tailable' | 'awaitData'>,
+    ClientBulkWriteOptions {}
+
+/**
+ * This is the cursor that handles client bulk write operations. Note this is never
+ * exposed directly to the user and is always immediately exhausted.
+ * @internal
+ */
+export class ClientBulkWriteCursor extends AbstractCursor {
+  commandBuilder: ClientBulkWriteCommandBuilder;
+  /** @internal */
+  private cursorResponse?: ClientBulkWriteCursorResponse;
+  /** @internal */
+  private clientBulkWriteOptions: ClientBulkWriteOptions;
+
+  /** @internal */
+  constructor(
+    client: MongoClient,
+    commandBuilder: ClientBulkWriteCommandBuilder,
+    options: ClientBulkWriteOptions = {}
+  ) {
+    super(client, new MongoDBNamespace('admin', '$cmd'), options);
+
+    this.commandBuilder = commandBuilder;
+    this.clientBulkWriteOptions = options;
+  }
+
+  /**
+   * We need a way to get the top level cursor response fields for
+   * generating the bulk write result, so we expose this here.
+   */
+  get response(): ClientBulkWriteCursorResponse | null {
+    if (this.cursorResponse) return this.cursorResponse;
+    return null;
+  }
+
+  get operations(): Document[] {
+    return this.commandBuilder.lastOperations;
+  }
+
+  clone(): ClientBulkWriteCursor {
+    const clonedOptions = mergeOptions({}, this.clientBulkWriteOptions);
+    delete clonedOptions.session;
+    return new ClientBulkWriteCursor(this.client, this.commandBuilder, {
+      ...clonedOptions
+    });
+  }
+
+  /** @internal */
+  async _initialize(session: ClientSession): Promise<InitialCursorResponse> {
+    const clientBulkWriteOperation = new ClientBulkWriteOperation(this.commandBuilder, {
+      ...this.clientBulkWriteOptions,
+      ...this.cursorOptions,
+      session
+    });
+
+    const response = await executeOperation(this.client, clientBulkWriteOperation);
+    this.cursorResponse = response;
+
+    return { server: clientBulkWriteOperation.server, session, response };
+  }
+}

package/src/cursor/find_cursor.ts

@@ -1,7 +1,7 @@
 import { type Document } from '../bson';
 import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
-import { type ExplainVerbosityLike } from '../explain';
+import { type ExplainCommandOptions, type ExplainVerbosityLike } from '../explain';
 import type { MongoClient } from '../mongo_client';
 import type { CollationOptions } from '../operations/command';
 import { CountOperation, type CountOptions } from '../operations/count';
@@ -133,7 +133,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
   }
 
   /** Execute the explain for the cursor */
-  async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
+  async explain(verbosity?: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document> {
     return (
       await executeOperation(
         this.client,

package/src/db.ts

@@ -279,7 +279,7 @@ export class Db {
   }
 
   /**
-   * Execute an aggregation framework pipeline against the database, needs MongoDB \>= 3.6
+   * Execute an aggregation framework pipeline against the database.
    *
    * @param pipeline - An array of aggregation stages to be executed
    * @param options - Optional settings for the command

package/src/error.ts

@@ -1,4 +1,8 @@
 import type { Document } from './bson';
+import {
+  type ClientBulkWriteError,
+  type ClientBulkWriteResult
+} from './operations/client_bulk_write/common';
 import type { ServerType } from './sdam/common';
 import type { TopologyVersion } from './sdam/server_description';
 import type { TopologyDescription } from './sdam/topology_description';
@@ -616,6 +620,98 @@ export class MongoGCPError extends MongoOIDCError {
   }
 }
 
+/**
+ * An error indicating that an error occurred when executing the bulk write.
+ *
+ * @public
+ * @category Error
+ */
+export class MongoClientBulkWriteError extends MongoServerError {
+  /**
+   * Write concern errors that occurred while executing the bulk write. This list may have
+   * multiple items if more than one server command was required to execute the bulk write.
+   */
+  writeConcernErrors: Document[];
+  /**
+   * Errors that occurred during the execution of individual write operations. This map will
+   * contain at most one entry if the bulk write was ordered.
+   */
+  writeErrors: Map<number, ClientBulkWriteError>;
+  /**
+   * The results of any successful operations that were performed before the error was
+   * encountered.
+   */
+  partialResult?: ClientBulkWriteResult;
+
+  /**
+   * Initialize the client bulk write error.
+   * @param message - The error message.
+   */
+  constructor(message: ErrorDescription) {
+    super(message);
+    this.writeConcernErrors = [];
+    this.writeErrors = new Map();
+  }
+
+  override get name(): string {
+    return 'MongoClientBulkWriteError';
+  }
+}
+
+/**
+ * An error indicating that an error occurred when processing bulk write results.
+ *
+ * @public
+ * @category Error
+ */
+export class MongoClientBulkWriteCursorError extends MongoRuntimeError {
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(message: string) {
+    super(message);
+  }
+
+  override get name(): string {
+    return 'MongoClientBulkWriteCursorError';
+  }
+}
+
+/**
+ * An error indicating that an error occurred on the client when executing a client bulk write.
+ *
+ * @public
+ * @category Error
+ */
+export class MongoClientBulkWriteExecutionError extends MongoRuntimeError {
+  /**
+   * **Do not use this constructor!**
+   *
+   * Meant for internal use only.
+   *
+   * @remarks
+   * This class is only meant to be constructed within the driver. This constructor is
+   * not subject to semantic versioning compatibility guarantees and may change at any time.
+   *
+   * @public
+   **/
+  constructor(message: string) {
+    super(message);
+  }
+
+  override get name(): string {
+    return 'MongoClientBulkWriteExecutionError';
+  }
+}
+
 /**
  * An error generated when a ChangeStream operation fails to execute.
  *
@@ -993,8 +1089,8 @@ export class MongoInvalidArgumentError extends MongoAPIError {
    *
    * @public
    **/
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: { cause?: Error }) {
+    super(message, options);
   }
 
   override get name(): string {

package/src/explain.ts

@@ -1,5 +1,3 @@
-import { MongoInvalidArgumentError } from './error';
-
 /** @public */
 export const ExplainVerbosity = Object.freeze({
   queryPlanner: 'queryPlanner',
@@ -13,23 +11,59 @@ export type ExplainVerbosity = string;
 
 /**
  * For backwards compatibility, true is interpreted as "allPlansExecution"
- * and false as "queryPlanner". Prior to server version 3.6, aggregate()
- * ignores the verbosity parameter and executes in "queryPlanner".
+ * and false as "queryPlanner".
  * @public
  */
 export type ExplainVerbosityLike = ExplainVerbosity | boolean;
 
 /** @public */
+export interface ExplainCommandOptions {
+  /** The explain verbosity for the command. */
+  verbosity: ExplainVerbosity;
+  /** The maxTimeMS setting for the command. */
+  maxTimeMS?: number;
+}
+
+/**
+ * @public
+ *
+ * When set, this configures an explain command.  Valid values are boolean (for legacy compatibility,
+ * see {@link ExplainVerbosityLike}), a string containing the explain verbosity, or an object containing the verbosity and
+ * an optional maxTimeMS.
+ *
+ * Examples of valid usage:
+ *
+ * ```typescript
+ * collection.find({ name: 'john doe' }, { explain: true });
+ * collection.find({ name: 'john doe' }, { explain: false });
+ * collection.find({ name: 'john doe' }, { explain: 'queryPlanner' });
+ * collection.find({ name: 'john doe' }, { explain: { verbosity: 'queryPlanner' } });
+ * ```
+ *
+ * maxTimeMS can be configured to limit the amount of time the server
+ * spends executing an explain by providing an object:
+ *
+ * ```typescript
+ * // limits the `explain` command to no more than 2 seconds
+ * collection.find({ name: 'john doe' }, {
+ *   explain:  {
+ *    verbosity: 'queryPlanner',
+ *    maxTimeMS: 2000
+ *  }
+ * });
+ * ```
+ */
 export interface ExplainOptions {
   /** Specifies the verbosity mode for the explain output. */
-  explain?: ExplainVerbosityLike;
+  explain?: ExplainVerbosityLike | ExplainCommandOptions;
 }
 
 /** @internal */
 export class Explain {
-  verbosity: ExplainVerbosity;
+  readonly verbosity: ExplainVerbosity;
+  readonly maxTimeMS?: number;
 
-  constructor(verbosity: ExplainVerbosityLike) {
+  private constructor(verbosity: ExplainVerbosityLike, maxTimeMS?: number) {
     if (typeof verbosity === 'boolean') {
       this.verbosity = verbosity
         ? ExplainVerbosity.allPlansExecution
@@ -37,16 +71,18 @@ export class Explain {
     } else {
       this.verbosity = verbosity;
     }
+
+    this.maxTimeMS = maxTimeMS;
   }
 
-  static fromOptions(options?: ExplainOptions): Explain | undefined {
-    if (options?.explain == null) return;
+  static fromOptions({ explain }: ExplainOptions = {}): Explain | undefined {
+    if (explain == null) return;
 
-    const explain = options.explain;
     if (typeof explain === 'boolean' || typeof explain === 'string') {
       return new Explain(explain);
     }
 
-    throw new MongoInvalidArgumentError('Field "explain" must be a string or a boolean');
+    const { verbosity, maxTimeMS } = explain;
+    return new Explain(verbosity, maxTimeMS);
   }
 }

package/src/index.ts

@@ -45,6 +45,9 @@ export {
   MongoAzureError,
   MongoBatchReExecutionError,
   MongoChangeStreamError,
+  MongoClientBulkWriteCursorError,
+  MongoClientBulkWriteError,
+  MongoClientBulkWriteExecutionError,
   MongoCompatibilityError,
   MongoCursorExhaustedError,
   MongoCursorInUseError,
@@ -368,7 +371,12 @@ export type { RunCursorCommandOptions } from './cursor/run_command_cursor';
 export type { DbOptions, DbPrivate } from './db';
 export type { Encrypter, EncrypterOptions } from './encrypter';
 export type { AnyError, ErrorDescription, MongoNetworkErrorOptions } from './error';
-export type { Explain, ExplainOptions, ExplainVerbosityLike } from './explain';
+export type {
+  Explain,
+  ExplainCommandOptions,
+  ExplainOptions,
+  ExplainVerbosityLike
+} from './explain';
 export type {
   GridFSBucketReadStreamOptions,
   GridFSBucketReadStreamOptionsWithRevision,
@@ -468,6 +476,23 @@ export type {
   AggregateOptions,
   DB_AGGREGATE_COLLECTION
 } from './operations/aggregate';
+export type {
+  AnyClientBulkWriteModel,
+  ClientBulkWriteError,
+  ClientBulkWriteModel,
+  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 ClientBulkWriteModel,
+  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';
@@ -325,7 +331,6 @@ export type MongoClientEvents = Pick<TopologyEvents, (typeof MONGO_CLIENT_EVENTS
 };
 
 /** @internal */
-
 const kOptions = Symbol('options');
 
 /**
@@ -477,6 +482,29 @@ 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<SchemaMap extends Record<string, Document> = Record<string, Document>>(
+    models: ReadonlyArray<ClientBulkWriteModel<SchemaMap>>,
+    options?: ClientBulkWriteOptions
+  ): Promise<ClientBulkWriteResult> {
+    if (this.autoEncrypter) {
+      throw new MongoInvalidArgumentError(
+        'MongoClient bulkWrite does not currently support automatic encryption.'
+      );
+    }
+    // We do not need schema type information past this point ("as any" is fine)
+    return await new ClientBulkWriteExecutor(
+      this,
+      models as any,
+      resolveOptions(this, options)
+    ).execute();
+  }
+
   /**
    * Connect to MongoDB using a url
    *

package/src/mongo_client_auth_providers.ts

@@ -1,7 +1,6 @@
 import { type AuthProvider } from './cmap/auth/auth_provider';
 import { GSSAPI } from './cmap/auth/gssapi';
 import { type AuthMechanismProperties } from './cmap/auth/mongo_credentials';
-import { MongoCR } from './cmap/auth/mongocr';
 import { MongoDBAWS } from './cmap/auth/mongodb_aws';
 import { MongoDBOIDC, OIDC_WORKFLOWS, type Workflow } from './cmap/auth/mongodb_oidc';
 import { AutomatedCallbackWorkflow } from './cmap/auth/mongodb_oidc/automated_callback_workflow';
@@ -16,7 +15,14 @@ import { MongoInvalidArgumentError } from './error';
 /** @internal */
 const AUTH_PROVIDERS = new Map<AuthMechanism | string, (workflow?: Workflow) => AuthProvider>([
   [AuthMechanism.MONGODB_AWS, () => new MongoDBAWS()],
-  [AuthMechanism.MONGODB_CR, () => new MongoCR()],
+  [
+    AuthMechanism.MONGODB_CR,
+    () => {
+      throw new MongoInvalidArgumentError(
+        'MONGODB-CR is no longer a supported auth mechanism in MongoDB 4.0+'
+      );
+    }
+  ],
   [AuthMechanism.MONGODB_GSSAPI, () => new GSSAPI()],
   [AuthMechanism.MONGODB_OIDC, (workflow?: Workflow) => new MongoDBOIDC(workflow)],
   [AuthMechanism.MONGODB_PLAIN, () => new Plain()],

package/src/mongo_types.ts

@@ -1,15 +1,16 @@
-import type { BSONType, ObjectIdLike } from 'bson';
 import { EventEmitter } from 'events';
 
 import type {
   Binary,
   BSONRegExp,
+  BSONType,
   Decimal128,
   Document,
   Double,
   Int32,
   Long,
   ObjectId,
+  ObjectIdLike,
   Timestamp
 } from './bson';
 import { type CommandStartedEvent } from './cmap/command_monitoring_events';

package/src/operations/aggregate.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 type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
 import { maxWireVersion, type MongoDBNamespace } from '../utils';
@@ -14,7 +15,7 @@ export const DB_AGGREGATE_COLLECTION = 1 as const;
 const MIN_WIRE_VERSION_$OUT_READ_CONCERN_SUPPORT = 8;
 
 /** @public */
-export interface AggregateOptions extends CommandOperationOptions {
+export interface AggregateOptions extends Omit<CommandOperationOptions, 'explain'> {
   /** allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 \>). */
   allowDiskUse?: boolean;
   /** The number of documents to return per batch. See [aggregation documentation](https://www.mongodb.com/docs/manual/reference/command/aggregate). */
@@ -35,6 +36,13 @@ export interface AggregateOptions extends CommandOperationOptions {
   let?: Document;
 
   out?: string;
+
+  /**
+   * Specifies the verbosity mode for the explain output.
+   * @deprecated This API is deprecated in favor of `collection.aggregate().explain()`
+   * or `db.aggregate().explain()`.
+   */
+  explain?: ExplainOptions['explain'];
 }
 
 /** @internal */