mongodb 6.8.2 → 6.9.0-dev.20240917.sha.20396e1b

package/src/cmap/connection_pool_events.ts

@@ -13,6 +13,7 @@ import {
   CONNECTION_READY
 } from '../constants';
 import type { MongoError } from '../error';
+import { now } from '../utils';
 import type { Connection } from './connection';
 import type { ConnectionPool, ConnectionPoolOptions } from './connection_pool';
 
@@ -126,12 +127,25 @@ export class ConnectionCreatedEvent extends ConnectionPoolMonitoringEvent {
 export class ConnectionReadyEvent extends ConnectionPoolMonitoringEvent {
   /** The id of the connection */
   connectionId: number | '<monitor>';
+  /**
+   * The time it took to establish the connection.
+   * In accordance with the definition of establishment of a connection
+   * specified by `ConnectionPoolOptions.maxConnecting`,
+   * it is the time elapsed between emitting a `ConnectionCreatedEvent`
+   * and emitting this event as part of the same checking out.
+   *
+   * Naturally, when establishing a connection is part of checking out,
+   * this duration is not greater than
+   * `ConnectionCheckedOutEvent.duration`.
+   */
+  durationMS: number;
   /** @internal */
   name = CONNECTION_READY;
 
   /** @internal */
-  constructor(pool: ConnectionPool, connection: Connection) {
+  constructor(pool: ConnectionPool, connection: Connection, connectionCreatedEventTime: number) {
     super(pool);
+    this.durationMS = now() - connectionCreatedEventTime;
     this.connectionId = connection.id;
   }
 }
@@ -194,14 +208,23 @@ export class ConnectionCheckOutFailedEvent extends ConnectionPoolMonitoringEvent
   error?: MongoError;
   /** @internal */
   name = CONNECTION_CHECK_OUT_FAILED;
+  /**
+   * The time it took to check out the connection.
+   * More specifically, the time elapsed between
+   * emitting a `ConnectionCheckOutStartedEvent`
+   * and emitting this event as part of the same check out.
+   */
+  durationMS: number;
 
   /** @internal */
   constructor(
     pool: ConnectionPool,
     reason: 'poolClosed' | 'timeout' | 'connectionError',
+    checkoutTime: number,
     error?: MongoError
   ) {
     super(pool);
+    this.durationMS = now() - checkoutTime;
     this.reason = reason;
     this.error = error;
   }
@@ -217,10 +240,19 @@ export class ConnectionCheckedOutEvent extends ConnectionPoolMonitoringEvent {
   connectionId: number | '<monitor>';
   /** @internal */
   name = CONNECTION_CHECKED_OUT;
+  /**
+   * The time it took to check out the connection.
+   * More specifically, the time elapsed between
+   * emitting a `ConnectionCheckOutStartedEvent`
+   * and emitting this event as part of the same checking out.
+   *
+   */
+  durationMS: number;
 
   /** @internal */
-  constructor(pool: ConnectionPool, connection: Connection) {
+  constructor(pool: ConnectionPool, connection: Connection, checkoutTime: number) {
     super(pool);
+    this.durationMS = now() - checkoutTime;
     this.connectionId = connection.id;
   }
 }

package/src/cmap/handshake/client_metadata.ts

@@ -6,7 +6,7 @@ import { MongoInvalidArgumentError } from '../../error';
 import type { MongoOptions } from '../../mongo_client';
 import { fileIsAccessible } from '../../utils';
 
-// eslint-disable-next-line @typescript-eslint/no-var-requires
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const NODE_DRIVER_VERSION = require('../../../package.json').version;
 
 /**

package/src/cmap/wire_protocol/constants.ts

@@ -1,7 +1,7 @@
-export const MIN_SUPPORTED_SERVER_VERSION = '3.6';
-export const MAX_SUPPORTED_SERVER_VERSION = '7.0';
-export const MIN_SUPPORTED_WIRE_VERSION = 6;
-export const MAX_SUPPORTED_WIRE_VERSION = 21;
+export const MIN_SUPPORTED_SERVER_VERSION = '4.0';
+export const MAX_SUPPORTED_SERVER_VERSION = '8.0';
+export const MIN_SUPPORTED_WIRE_VERSION = 7;
+export const MAX_SUPPORTED_WIRE_VERSION = 25;
 export const MIN_SUPPORTED_QE_WIRE_VERSION = 21;
 export const MIN_SUPPORTED_QE_SERVER_VERSION = '7.0';
 export const OP_REPLY = 1;

package/src/cmap/wire_protocol/shared.ts

@@ -1,6 +1,5 @@
 import { MongoInvalidArgumentError } from '../../error';
-import type { ReadPreferenceLike } from '../../read_preference';
-import { ReadPreference } from '../../read_preference';
+import { ReadPreference, type ReadPreferenceLike } from '../../read_preference';
 import { ServerType } from '../../sdam/common';
 import type { Server } from '../../sdam/server';
 import type { ServerDescription } from '../../sdam/server_description';

package/src/collection.ts

@@ -47,17 +47,18 @@ import {
   FindOneAndUpdateOperation,
   type FindOneAndUpdateOptions
 } from './operations/find_and_modify';
-import type {
-  CreateIndexesOptions,
-  DropIndexesOptions,
-  IndexDescription,
-  IndexDescriptionCompact,
-  IndexDescriptionInfo,
-  IndexInformationOptions,
-  IndexSpecification,
-  ListIndexesOptions
+import {
+  CreateIndexesOperation,
+  type CreateIndexesOptions,
+  type DropIndexesOptions,
+  DropIndexOperation,
+  type IndexDescription,
+  type IndexDescriptionCompact,
+  type IndexDescriptionInfo,
+  type IndexInformationOptions,
+  type IndexSpecification,
+  type ListIndexesOptions
 } from './operations/indexes';
-import { CreateIndexesOperation, DropIndexOperation } from './operations/indexes';
 import {
   InsertManyOperation,
   type InsertManyResult,
@@ -292,7 +293,7 @@ export class Collection<TSchema extends Document = Document> {
    * @param options - Optional settings for the command
    */
   async insertMany(
-    docs: OptionalUnlessRequiredId<TSchema>[],
+    docs: ReadonlyArray<OptionalUnlessRequiredId<TSchema>>,
     options?: BulkWriteOptions
   ): Promise<InsertManyResult<TSchema>> {
     return await executeOperation(
@@ -325,7 +326,7 @@ export class Collection<TSchema extends Document = Document> {
    * @throws MongoDriverError if operations is not an array
    */
   async bulkWrite(
-    operations: AnyBulkWriteOperation<TSchema>[],
+    operations: ReadonlyArray<AnyBulkWriteOperation<TSchema>>,
     options?: BulkWriteOptions
   ): Promise<BulkWriteResult> {
     if (!Array.isArray(operations)) {
@@ -336,7 +337,7 @@ export class Collection<TSchema extends Document = Document> {
       this.client,
       new BulkWriteOperation(
         this as TODO_NODE_3286,
-        operations as TODO_NODE_3286,
+        operations,
         resolveOptions(this, options ?? { ordered: true })
       )
     );
@@ -1121,8 +1122,8 @@ export class Collection<TSchema extends Document = Document> {
       indexNameOrOptions == null
         ? null
         : typeof indexNameOrOptions === 'object'
-        ? null
-        : indexNameOrOptions;
+          ? null
+          : indexNameOrOptions;
 
     return new ListSearchIndexesCursor(this as TODO_NODE_3286, indexName, options);
   }

package/src/connection_string.ts

@@ -73,7 +73,7 @@ export async function resolveSRVRecord(options: MongoOptions): Promise<HostAddre
   // the SRV record is resolved before starting a second DNS query.
   const lookupAddress = options.srvHost;
   const txtResolutionPromise = dns.promises.resolveTxt(lookupAddress);
-  // eslint-disable-next-line github/no-then
+
   txtResolutionPromise.then(undefined, squashError); // rejections will be handled later
 
   // Resolve the SRV record and use the result as the list of hosts to connect to.
@@ -552,7 +552,6 @@ export function parseOptions(
 
   mongoOptions.metadata = makeClientMetadata(mongoOptions);
 
-  // eslint-disable-next-line github/no-then
   mongoOptions.extendedMetadata = addContainerMetadata(mongoOptions.metadata).then(
     undefined,
     squashError
@@ -740,6 +739,13 @@ export const OPTIONS = {
   autoEncryption: {
     type: 'record'
   },
+  autoSelectFamily: {
+    type: 'boolean',
+    default: true
+  },
+  autoSelectFamilyAttemptTimeout: {
+    type: 'uint'
+  },
   bsonRegExp: {
     type: 'boolean'
   },
@@ -1222,7 +1228,8 @@ export const OPTIONS = {
   // Custom types for modifying core behavior
   connectionType: { type: 'any' },
   srvPoller: { type: 'any' },
-  // Accepted NodeJS Options
+  // Accepted Node.js Options
+  allowPartialTrustChain: { type: 'any' },
   minDHSize: { type: 'any' },
   pskCallback: { type: 'any' },
   secureContext: { type: 'any' },

package/src/constants.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unnecessary-type-assertion */
 export const SYSTEM_NAMESPACE_COLLECTION = 'system.namespaces';
 export const SYSTEM_INDEX_COLLECTION = 'system.indexes';
 export const SYSTEM_PROFILE_COLLECTION = 'system.profile';

package/src/cursor/abstract_cursor.ts

@@ -18,6 +18,7 @@ import { GetMoreOperation } from '../operations/get_more';
 import { KillCursorsOperation } from '../operations/kill_cursors';
 import { ReadConcern, type ReadConcernLike } from '../read_concern';
 import { ReadPreference, type ReadPreferenceLike } from '../read_preference';
+import { type AsyncDisposable, configureResourceManagement } from '../resource_management';
 import type { Server } from '../sdam/server';
 import { ClientSession, maybeClearPinnedConnection } from '../sessions';
 import { type MongoDBNamespace, squashError } from '../utils';
@@ -125,9 +126,12 @@ export type AbstractCursorEvents = {
 
 /** @public */
 export abstract class AbstractCursor<
-  TSchema = any,
-  CursorEvents extends AbstractCursorEvents = AbstractCursorEvents
-> extends TypedEventEmitter<CursorEvents> {
+    TSchema = any,
+    CursorEvents extends AbstractCursorEvents = AbstractCursorEvents
+  >
+  extends TypedEventEmitter<CursorEvents>
+  implements AsyncDisposable
+{
   /** @internal */
   private cursorId: Long | null;
   /** @internal */
@@ -286,14 +290,25 @@ export abstract class AbstractCursor<
     return !!this.cursorClient.topology?.loadBalanced;
   }
 
+  /**
+   * @beta
+   * @experimental
+   * An alias for {@link AbstractCursor.close|AbstractCursor.close()}.
+   */
+  declare [Symbol.asyncDispose]: () => Promise<void>;
+  /** @internal */
+  async asyncDispose() {
+    await this.close();
+  }
+
   /** Returns current buffered documents length */
   bufferedCount(): number {
     return this.documents?.length ?? 0;
   }
 
   /** Returns current buffered documents */
-  readBufferedDocuments(number?: number): TSchema[] {
-    const bufferedDocs: TSchema[] = [];
+  readBufferedDocuments(number?: number): NonNullable<TSchema>[] {
+    const bufferedDocs: NonNullable<TSchema>[] = [];
     const documentsToRead = Math.min(
       number ?? this.documents?.length ?? 0,
       this.documents?.length ?? 0
@@ -308,6 +323,7 @@ export abstract class AbstractCursor<
 
     return bufferedDocs;
   }
+
   async *[Symbol.asyncIterator](): AsyncGenerator<TSchema, void, void> {
     if (this.closed) {
       return;
@@ -457,6 +473,9 @@ export abstract class AbstractCursor<
     }
   }
 
+  /**
+   * Frees any client-side resources used by the cursor.
+   */
   async close(): Promise<void> {
     await this.cleanup();
   }
@@ -468,13 +487,22 @@ export abstract class AbstractCursor<
    * cursor.rewind() can be used to reset the cursor.
    */
   async toArray(): Promise<TSchema[]> {
-    const array = [];
+    const array: TSchema[] = [];
+    // at the end of the loop (since readBufferedDocuments is called) the buffer will be empty
+    // then, the 'await of' syntax will run a getMore call
     for await (const document of this) {
       array.push(document);
+      const docs = this.readBufferedDocuments();
+      if (this.transform != null) {
+        for (const doc of docs) {
+          array.push(await this.transformDocument(doc));
+        }
+      } else {
+        array.push(...docs);
+      }
     }
     return array;
   }
-
   /**
    * Add a cursor flag to the cursor
    *
@@ -639,7 +667,6 @@ export abstract class AbstractCursor<
       // We only want to end this session if we created it, and it hasn't ended yet
       if (session.explicit === false) {
         if (!session.hasEnded) {
-          // eslint-disable-next-line github/no-then
           session.endSession().then(undefined, squashError);
         }
         this.cursorSession = this.cursorClient.startSession({ owner: this, explicit: false });
@@ -815,7 +842,7 @@ export abstract class AbstractCursor<
   }
 
   /** @internal */
-  private async transformDocument(document: NonNullable<TSchema>): Promise<TSchema> {
+  private async transformDocument(document: NonNullable<TSchema>): Promise<NonNullable<TSchema>> {
     if (this.transform == null) return document;
 
     try {
@@ -865,7 +892,6 @@ class ReadableCursorStream extends Readable {
   }
 
   override _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
-    // eslint-disable-next-line github/no-then
     this._cursor.close().then(
       () => callback(error),
       closeError => callback(closeError)
@@ -878,13 +904,11 @@ class ReadableCursorStream extends Readable {
       return;
     }
 
-    // eslint-disable-next-line github/no-then
     this._cursor.next().then(
       result => {
         if (result == null) {
           this.push(null);
         } else if (this.destroyed) {
-          // eslint-disable-next-line github/no-then
           this._cursor.close().then(undefined, squashError);
         } else {
           if (this.push(result)) {
@@ -900,7 +924,6 @@ class ReadableCursorStream extends Readable {
         //       a client during iteration. Alternatively, we could do the "right" thing and
         //       propagate the error message by removing this special case.
         if (err.message.match(/server is closed/)) {
-          // eslint-disable-next-line github/no-then
           this._cursor.close().then(undefined, squashError);
           return this.push(null);
         }
@@ -927,3 +950,5 @@ class ReadableCursorStream extends Readable {
     );
   }
 }
+
+configureResourceManagement(AbstractCursor.prototype);

package/src/cursor/aggregation_cursor.ts

@@ -1,14 +1,16 @@
 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';
 import type { ClientSession } from '../sessions';
 import type { Sort } from '../sort';
-import type { MongoDBNamespace } from '../utils';
-import { mergeOptions } from '../utils';
-import type { AbstractCursorOptions, InitialCursorResponse } from './abstract_cursor';
-import { AbstractCursor } from './abstract_cursor';
+import { mergeOptions, type MongoDBNamespace } from '../utils';
+import {
+  AbstractCursor,
+  type AbstractCursorOptions,
+  type InitialCursorResponse
+} from './abstract_cursor';
 
 /** @public */
 export interface AggregationCursorOptions extends AbstractCursorOptions, AggregateOptions {}
@@ -64,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/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/deps.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
 import { type Stream } from './cmap/connect';
 import { MongoMissingDependencyError } from './error';
 import type { Callback } from './utils';
@@ -24,6 +23,7 @@ export function getKerberos(): Kerberos {
   let kerberos: Kerberos;
   try {
     // Ensure you always wrap an optional require in the try block NODE-3199
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     kerberos = require('kerberos');
   } catch (error) {
     kerberos = makeErrorModule(
@@ -63,6 +63,7 @@ export type ZStandard = ZStandardLib | { kModuleError: MongoMissingDependencyErr
 export function getZstdLibrary(): ZStandardLib | { kModuleError: MongoMissingDependencyError } {
   let ZStandard: ZStandardLib | { kModuleError: MongoMissingDependencyError };
   try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     ZStandard = require('@mongodb-js/zstd');
   } catch (error) {
     ZStandard = makeErrorModule(
@@ -101,6 +102,7 @@ export function getAwsCredentialProvider():
   | { kModuleError: MongoMissingDependencyError } {
   try {
     // Ensure you always wrap an optional require in the try block NODE-3199
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const credentialProvider = require('@aws-sdk/credential-providers');
     return credentialProvider;
   } catch (error) {
@@ -122,6 +124,7 @@ export type GcpMetadata =
 export function getGcpMetadata(): GcpMetadata {
   try {
     // Ensure you always wrap an optional require in the try block NODE-3199
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const credentialProvider = require('gcp-metadata');
     return credentialProvider;
   } catch (error) {
@@ -153,6 +156,7 @@ export type SnappyLib = {
 export function getSnappy(): SnappyLib | { kModuleError: MongoMissingDependencyError } {
   try {
     // Ensure you always wrap an optional require in the try block NODE-3199
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const value = require('snappy');
     return value;
   } catch (error) {
@@ -187,6 +191,7 @@ export type SocksLib = {
 export function getSocks(): SocksLib | { kModuleError: MongoMissingDependencyError } {
   try {
     // Ensure you always wrap an optional require in the try block NODE-3199
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const value = require('socks');
     return value;
   } catch (error) {
@@ -244,6 +249,7 @@ export const aws4: AWS4 | { kModuleError: MongoMissingDependencyError } = loadAw
 function loadAws4() {
   let aws4: AWS4 | { kModuleError: MongoMissingDependencyError };
   try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     aws4 = require('aws4');
   } catch (error) {
     aws4 = makeErrorModule(
@@ -267,6 +273,7 @@ export function getMongoDBClientEncryption():
     // NOTE(NODE-3199): Ensure you always wrap an optional require literally in the try block
     // Cannot be moved to helper utility function, bundlers search and replace the actual require call
     // in a way that makes this line throw at bundle time, not runtime, catching here will make bundling succeed
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     mongodbClientEncryption = require('mongodb-client-encryption');
   } catch (error) {
     const kModuleError = new MongoMissingDependencyError(

package/src/error.ts

@@ -1,4 +1,5 @@
 import type { Document } from './bson';
+import type { ServerType } from './sdam/common';
 import type { TopologyVersion } from './sdam/server_description';
 import type { TopologyDescription } from './sdam/topology_description';
 
@@ -1158,6 +1159,23 @@ export class MongoServerSelectionError extends MongoSystemError {
   }
 }
 
+/**
+ * The type of the result property of MongoWriteConcernError
+ * @public
+ */
+export interface WriteConcernErrorResult {
+  writeConcernError: {
+    code: number;
+    errmsg: string;
+    codeName?: string;
+    errInfo?: Document;
+  };
+  ok: number;
+  code?: number;
+  errorLabels?: string[];
+  [x: string | number]: unknown;
+}
+
 /**
  * An error thrown when the server reports a writeConcernError
  * @public
@@ -1178,16 +1196,8 @@ export class MongoWriteConcernError extends MongoServerError {
    *
    * @public
    **/
-  constructor(result: {
-    writeConcernError: {
-      code: number;
-      errmsg: string;
-      codeName?: string;
-      errInfo?: Document;
-    };
-    errorLabels?: string[];
-  }) {
-    super({ ...result, ...result.writeConcernError });
+  constructor(result: WriteConcernErrorResult) {
+    super({ ...result.writeConcernError, ...result });
     this.errInfo = result.writeConcernError.errInfo;
     this.result = result;
   }
@@ -1217,7 +1227,11 @@ const RETRYABLE_READ_ERROR_CODES = new Set<number>([
 // see: https://github.com/mongodb/specifications/blob/master/source/retryable-writes/retryable-writes.rst#terms
 const RETRYABLE_WRITE_ERROR_CODES = RETRYABLE_READ_ERROR_CODES;
 
-export function needsRetryableWriteLabel(error: Error, maxWireVersion: number): boolean {
+export function needsRetryableWriteLabel(
+  error: Error,
+  maxWireVersion: number,
+  serverType: ServerType
+): boolean {
   // pre-4.4 server, then the driver adds an error label for every valid case
   // execute operation will only inspect the label, code/message logic is handled here
   if (error instanceof MongoNetworkError) {
@@ -1237,11 +1251,16 @@ export function needsRetryableWriteLabel(error: Error, maxWireVersion: number):
   }
 
   if (error instanceof MongoWriteConcernError) {
-    return RETRYABLE_WRITE_ERROR_CODES.has(error.result?.code ?? error.code ?? 0);
+    if (serverType === 'Mongos' && maxWireVersion < 9) {
+      // use original top-level code from server response
+      return RETRYABLE_WRITE_ERROR_CODES.has(error.result.code ?? 0);
+    }
+    const code = error.result.writeConcernError.code ?? Number(error.code);
+    return RETRYABLE_WRITE_ERROR_CODES.has(Number.isNaN(code) ? 0 : code);
   }
 
-  if (error instanceof MongoError && typeof error.code === 'number') {
-    return RETRYABLE_WRITE_ERROR_CODES.has(error.code);
+  if (error instanceof MongoError) {
+    return RETRYABLE_WRITE_ERROR_CODES.has(Number(error.code));
   }
 
   const isNotWritablePrimaryError = LEGACY_NOT_WRITABLE_PRIMARY_ERROR_MESSAGE.test(error.message);

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);
   }
 }