mongodb 6.10.0-dev.20241106.sha.dc3fe957 → 6.10.0-dev.20241107.sha.e5582ed7

package/src/gridfs/index.ts

@@ -2,10 +2,12 @@ import type { ObjectId } from '../bson';
 import type { Collection } from '../collection';
 import type { FindCursor } from '../cursor/find_cursor';
 import type { Db } from '../db';
-import { MongoRuntimeError } from '../error';
+import { MongoOperationTimeoutError, MongoRuntimeError } from '../error';
 import { type Filter, TypedEventEmitter } from '../mongo_types';
 import type { ReadPreference } from '../read_preference';
 import type { Sort } from '../sort';
+import { CSOTTimeoutContext } from '../timeout';
+import { resolveOptions } from '../utils';
 import { WriteConcern, type WriteConcernOptions } from '../write_concern';
 import type { FindOptions } from './../operations/find';
 import {
@@ -36,7 +38,11 @@ export interface GridFSBucketOptions extends WriteConcernOptions {
   chunkSizeBytes?: number;
   /** Read preference to be passed to read operations */
   readPreference?: ReadPreference;
-  /** @internal TODO(NODE-5688): make this public */
+  /**
+   * @experimental
+   * Specifies the lifetime duration of a gridFS stream. If any async operations are in progress
+   * when this timeout expires, the stream will throw a timeout error.
+   */
   timeoutMS?: number;
 }
 
@@ -48,6 +54,7 @@ export interface GridFSBucketPrivate {
     chunkSizeBytes: number;
     readPreference?: ReadPreference;
     writeConcern: WriteConcern | undefined;
+    timeoutMS?: number;
   };
   _chunksCollection: Collection<GridFSChunk>;
   _filesCollection: Collection<GridFSFile>;
@@ -81,11 +88,11 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
   constructor(db: Db, options?: GridFSBucketOptions) {
     super();
     this.setMaxListeners(0);
-    const privateOptions = {
+    const privateOptions = resolveOptions(db, {
       ...DEFAULT_GRIDFS_BUCKET_OPTIONS,
       ...options,
       writeConcern: WriteConcern.fromOptions(options)
-    };
+    });
     this.s = {
       db,
       options: privateOptions,
@@ -109,7 +116,10 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
     filename: string,
     options?: GridFSBucketWriteStreamOptions
   ): GridFSBucketWriteStream {
-    return new GridFSBucketWriteStream(this, filename, options);
+    return new GridFSBucketWriteStream(this, filename, {
+      timeoutMS: this.s.options.timeoutMS,
+      ...options
+    });
   }
 
   /**
@@ -122,7 +132,11 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
     filename: string,
     options?: GridFSBucketWriteStreamOptions
   ): GridFSBucketWriteStream {
-    return new GridFSBucketWriteStream(this, filename, { ...options, id });
+    return new GridFSBucketWriteStream(this, filename, {
+      timeoutMS: this.s.options.timeoutMS,
+      ...options,
+      id
+    });
   }
 
   /** Returns a readable stream (GridFSBucketReadStream) for streaming file data from GridFS. */
@@ -135,7 +149,7 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
       this.s._filesCollection,
       this.s.options.readPreference,
       { _id: id },
-      options
+      { timeoutMS: this.s.options.timeoutMS, ...options }
     );
   }
 
@@ -144,11 +158,27 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
    *
    * @param id - The id of the file doc
    */
-  async delete(id: ObjectId): Promise<void> {
-    const { deletedCount } = await this.s._filesCollection.deleteOne({ _id: id });
+  async delete(id: ObjectId, options?: { timeoutMS: number }): Promise<void> {
+    const { timeoutMS } = resolveOptions(this.s.db, options);
+    let timeoutContext: CSOTTimeoutContext | undefined = undefined;
 
+    if (timeoutMS) {
+      timeoutContext = new CSOTTimeoutContext({
+        timeoutMS,
+        serverSelectionTimeoutMS: this.s.db.client.s.options.serverSelectionTimeoutMS
+      });
+    }
+
+    const { deletedCount } = await this.s._filesCollection.deleteOne(
+      { _id: id },
+      { timeoutMS: timeoutContext?.remainingTimeMS }
+    );
+
+    const remainingTimeMS = timeoutContext?.remainingTimeMS;
+    if (remainingTimeMS != null && remainingTimeMS <= 0)
+      throw new MongoOperationTimeoutError(`Timed out after ${timeoutMS}ms`);
     // Delete orphaned chunks before returning FileNotFound
-    await this.s._chunksCollection.deleteMany({ files_id: id });
+    await this.s._chunksCollection.deleteMany({ files_id: id }, { timeoutMS: remainingTimeMS });
 
     if (deletedCount === 0) {
       // TODO(NODE-3483): Replace with more appropriate error
@@ -188,7 +218,7 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
       this.s._filesCollection,
       this.s.options.readPreference,
       { filename },
-      { ...options, sort, skip }
+      { timeoutMS: this.s.options.timeoutMS, ...options, sort, skip }
     );
   }
 
@@ -198,18 +228,36 @@ export class GridFSBucket extends TypedEventEmitter<GridFSBucketEvents> {
    * @param id - the id of the file to rename
    * @param filename - new name for the file
    */
-  async rename(id: ObjectId, filename: string): Promise<void> {
+  async rename(id: ObjectId, filename: string, options?: { timeoutMS: number }): Promise<void> {
     const filter = { _id: id };
     const update = { $set: { filename } };
-    const { matchedCount } = await this.s._filesCollection.updateOne(filter, update);
+    const { matchedCount } = await this.s._filesCollection.updateOne(filter, update, options);
     if (matchedCount === 0) {
       throw new MongoRuntimeError(`File with id ${id} not found`);
     }
   }
 
   /** Removes this bucket's files collection, followed by its chunks collection. */
-  async drop(): Promise<void> {
-    await this.s._filesCollection.drop();
-    await this.s._chunksCollection.drop();
+  async drop(options?: { timeoutMS: number }): Promise<void> {
+    const { timeoutMS } = resolveOptions(this.s.db, options);
+    let timeoutContext: CSOTTimeoutContext | undefined = undefined;
+
+    if (timeoutMS) {
+      timeoutContext = new CSOTTimeoutContext({
+        timeoutMS,
+        serverSelectionTimeoutMS: this.s.db.client.s.options.serverSelectionTimeoutMS
+      });
+    }
+
+    if (timeoutContext) {
+      await this.s._filesCollection.drop({ timeoutMS: timeoutContext.remainingTimeMS });
+      const remainingTimeMS = timeoutContext.getRemainingTimeMSOrThrow(
+        `Timed out after ${timeoutMS}ms`
+      );
+      await this.s._chunksCollection.drop({ timeoutMS: remainingTimeMS });
+    } else {
+      await this.s._filesCollection.drop();
+      await this.s._chunksCollection.drop();
+    }
   }
 }

package/src/gridfs/upload.ts

@@ -2,8 +2,15 @@ import { Writable } from 'stream';
 
 import { type Document, ObjectId } from '../bson';
 import type { Collection } from '../collection';
-import { MongoAPIError, MONGODB_ERROR_CODES, MongoError } from '../error';
-import { type Callback, squashError } from '../utils';
+import { CursorTimeoutMode } from '../cursor/abstract_cursor';
+import {
+  MongoAPIError,
+  MONGODB_ERROR_CODES,
+  MongoError,
+  MongoOperationTimeoutError
+} from '../error';
+import { CSOTTimeoutContext } from '../timeout';
+import { type Callback, resolveTimeoutOptions, squashError } from '../utils';
 import type { WriteConcernOptions } from '../write_concern';
 import { WriteConcern } from './../write_concern';
 import type { GridFSFile } from './download';
@@ -35,7 +42,10 @@ export interface GridFSBucketWriteStreamOptions extends WriteConcernOptions {
    * @deprecated Will be removed in the next major version. Add an aliases field to the metadata document instead.
    */
   aliases?: string[];
-  /** @internal TODO(NODE-5688): make this public */
+  /**
+   * @experimental
+   * Specifies the time an operation will run until it throws a timeout error
+   */
   timeoutMS?: number;
 }
 
@@ -97,6 +107,8 @@ export class GridFSBucketWriteStream extends Writable {
    * ```
    */
   gridFSFile: GridFSFile | null = null;
+  /** @internal */
+  timeoutContext?: CSOTTimeoutContext;
 
   /**
    * @param bucket - Handle for this stream's corresponding bucket
@@ -131,14 +143,12 @@ export class GridFSBucketWriteStream extends Writable {
       aborted: false
     };
 
-    if (!this.bucket.s.calledOpenUploadStream) {
-      this.bucket.s.calledOpenUploadStream = true;
-
-      checkIndexes(this).then(() => {
-        this.bucket.s.checkedIndexes = true;
-        this.bucket.emit('index');
-      }, squashError);
-    }
+    if (options.timeoutMS != null)
+      this.timeoutContext = new CSOTTimeoutContext({
+        timeoutMS: options.timeoutMS,
+        serverSelectionTimeoutMS: resolveTimeoutOptions(this.bucket.s.db.client, {})
+          .serverSelectionTimeoutMS
+      });
   }
 
   /**
@@ -147,10 +157,26 @@ export class GridFSBucketWriteStream extends Writable {
    * The stream is considered constructed when the indexes are done being created
    */
   override _construct(callback: (error?: Error | null) => void): void {
-    if (this.bucket.s.checkedIndexes) {
+    if (!this.bucket.s.calledOpenUploadStream) {
+      this.bucket.s.calledOpenUploadStream = true;
+
+      checkIndexes(this).then(
+        () => {
+          this.bucket.s.checkedIndexes = true;
+          this.bucket.emit('index');
+          callback();
+        },
+        error => {
+          if (error instanceof MongoOperationTimeoutError) {
+            return handleError(this, error, callback);
+          }
+          squashError(error);
+          callback();
+        }
+      );
+    } else {
       return process.nextTick(callback);
     }
-    this.bucket.once('index', callback);
   }
 
   /**
@@ -194,7 +220,10 @@ export class GridFSBucketWriteStream extends Writable {
     }
 
     this.state.aborted = true;
-    await this.chunks.deleteMany({ files_id: this.id });
+    const remainingTimeMS = this.timeoutContext?.getRemainingTimeMSOrThrow(
+      `Upload timed out after ${this.timeoutContext?.timeoutMS}ms`
+    );
+    await this.chunks.deleteMany({ files_id: this.id, timeoutMS: remainingTimeMS });
   }
 }
 
@@ -219,9 +248,19 @@ function createChunkDoc(filesId: ObjectId, n: number, data: Buffer): GridFSChunk
 async function checkChunksIndex(stream: GridFSBucketWriteStream): Promise<void> {
   const index = { files_id: 1, n: 1 };
 
+  let remainingTimeMS;
+  remainingTimeMS = stream.timeoutContext?.getRemainingTimeMSOrThrow(
+    `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+  );
+
   let indexes;
   try {
-    indexes = await stream.chunks.listIndexes().toArray();
+    indexes = await stream.chunks
+      .listIndexes({
+        timeoutMode: remainingTimeMS != null ? CursorTimeoutMode.LIFETIME : undefined,
+        timeoutMS: remainingTimeMS
+      })
+      .toArray();
   } catch (error) {
     if (error instanceof MongoError && error.code === MONGODB_ERROR_CODES.NamespaceNotFound) {
       indexes = [];
@@ -239,10 +278,14 @@ async function checkChunksIndex(stream: GridFSBucketWriteStream): Promise<void>
   });
 
   if (!hasChunksIndex) {
+    remainingTimeMS = stream.timeoutContext?.getRemainingTimeMSOrThrow(
+      `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+    );
     await stream.chunks.createIndex(index, {
       ...stream.writeConcern,
       background: true,
-      unique: true
+      unique: true,
+      timeoutMS: remainingTimeMS
     });
   }
 }
@@ -270,13 +313,28 @@ function checkDone(stream: GridFSBucketWriteStream, callback: Callback): void {
       return;
     }
 
-    stream.files.insertOne(gridFSFile, { writeConcern: stream.writeConcern }).then(
-      () => {
-        stream.gridFSFile = gridFSFile;
-        callback();
-      },
-      error => handleError(stream, error, callback)
-    );
+    const remainingTimeMS = stream.timeoutContext?.remainingTimeMS;
+    if (remainingTimeMS != null && remainingTimeMS <= 0) {
+      return handleError(
+        stream,
+        new MongoOperationTimeoutError(
+          `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+        ),
+        callback
+      );
+    }
+
+    stream.files
+      .insertOne(gridFSFile, { writeConcern: stream.writeConcern, timeoutMS: remainingTimeMS })
+      .then(
+        () => {
+          stream.gridFSFile = gridFSFile;
+          callback();
+        },
+        error => {
+          return handleError(stream, error, callback);
+        }
+      );
     return;
   }
 
@@ -284,7 +342,16 @@ function checkDone(stream: GridFSBucketWriteStream, callback: Callback): void {
 }
 
 async function checkIndexes(stream: GridFSBucketWriteStream): Promise<void> {
-  const doc = await stream.files.findOne({}, { projection: { _id: 1 } });
+  let remainingTimeMS = stream.timeoutContext?.getRemainingTimeMSOrThrow(
+    `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+  );
+  const doc = await stream.files.findOne(
+    {},
+    {
+      projection: { _id: 1 },
+      timeoutMS: remainingTimeMS
+    }
+  );
   if (doc != null) {
     // If at least one document exists assume the collection has the required index
     return;
@@ -293,8 +360,15 @@ async function checkIndexes(stream: GridFSBucketWriteStream): Promise<void> {
   const index = { filename: 1, uploadDate: 1 };
 
   let indexes;
+  remainingTimeMS = stream.timeoutContext?.getRemainingTimeMSOrThrow(
+    `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+  );
+  const listIndexesOptions = {
+    timeoutMode: remainingTimeMS != null ? CursorTimeoutMode.LIFETIME : undefined,
+    timeoutMS: remainingTimeMS
+  };
   try {
-    indexes = await stream.files.listIndexes().toArray();
+    indexes = await stream.files.listIndexes(listIndexesOptions).toArray();
   } catch (error) {
     if (error instanceof MongoError && error.code === MONGODB_ERROR_CODES.NamespaceNotFound) {
       indexes = [];
@@ -312,7 +386,11 @@ async function checkIndexes(stream: GridFSBucketWriteStream): Promise<void> {
   });
 
   if (!hasFileIndex) {
-    await stream.files.createIndex(index, { background: false });
+    remainingTimeMS = stream.timeoutContext?.getRemainingTimeMSOrThrow(
+      `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+    );
+
+    await stream.files.createIndex(index, { background: false, timeoutMS: remainingTimeMS });
   }
 
   await checkChunksIndex(stream);
@@ -386,6 +464,18 @@ function doWrite(
     let doc: GridFSChunk;
     if (spaceRemaining === 0) {
       doc = createChunkDoc(stream.id, stream.n, Buffer.from(stream.bufToStore));
+
+      const remainingTimeMS = stream.timeoutContext?.remainingTimeMS;
+      if (remainingTimeMS != null && remainingTimeMS <= 0) {
+        return handleError(
+          stream,
+          new MongoOperationTimeoutError(
+            `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+          ),
+          callback
+        );
+      }
+
       ++stream.state.outstandingRequests;
       ++outstandingRequests;
 
@@ -393,17 +483,21 @@ function doWrite(
         return;
       }
 
-      stream.chunks.insertOne(doc, { writeConcern: stream.writeConcern }).then(
-        () => {
-          --stream.state.outstandingRequests;
-          --outstandingRequests;
-
-          if (!outstandingRequests) {
-            checkDone(stream, callback);
+      stream.chunks
+        .insertOne(doc, { writeConcern: stream.writeConcern, timeoutMS: remainingTimeMS })
+        .then(
+          () => {
+            --stream.state.outstandingRequests;
+            --outstandingRequests;
+
+            if (!outstandingRequests) {
+              checkDone(stream, callback);
+            }
+          },
+          error => {
+            return handleError(stream, error, callback);
           }
-        },
-        error => handleError(stream, error, callback)
-      );
+        );
 
       spaceRemaining = stream.chunkSizeBytes;
       stream.pos = 0;
@@ -420,8 +514,6 @@ function writeRemnant(stream: GridFSBucketWriteStream, callback: Callback): void
     return checkDone(stream, callback);
   }
 
-  ++stream.state.outstandingRequests;
-
   // Create a new buffer to make sure the buffer isn't bigger than it needs
   // to be.
   const remnant = Buffer.alloc(stream.pos);
@@ -433,13 +525,28 @@ function writeRemnant(stream: GridFSBucketWriteStream, callback: Callback): void
     return;
   }
 
-  stream.chunks.insertOne(doc, { writeConcern: stream.writeConcern }).then(
-    () => {
-      --stream.state.outstandingRequests;
-      checkDone(stream, callback);
-    },
-    error => handleError(stream, error, callback)
-  );
+  const remainingTimeMS = stream.timeoutContext?.remainingTimeMS;
+  if (remainingTimeMS != null && remainingTimeMS <= 0) {
+    return handleError(
+      stream,
+      new MongoOperationTimeoutError(
+        `Upload timed out after ${stream.timeoutContext?.timeoutMS}ms`
+      ),
+      callback
+    );
+  }
+  ++stream.state.outstandingRequests;
+  stream.chunks
+    .insertOne(doc, { writeConcern: stream.writeConcern, timeoutMS: remainingTimeMS })
+    .then(
+      () => {
+        --stream.state.outstandingRequests;
+        checkDone(stream, callback);
+      },
+      error => {
+        return handleError(stream, error, callback);
+      }
+    );
 }
 
 function isAborted(stream: GridFSBucketWriteStream, callback: Callback<void>): boolean {

package/src/index.ts

@@ -10,6 +10,7 @@ import { ListCollectionsCursor } from './cursor/list_collections_cursor';
 import { ListIndexesCursor } from './cursor/list_indexes_cursor';
 import type { RunCommandCursor } from './cursor/run_command_cursor';
 import { Db } from './db';
+import { ExplainableCursor } from './explain';
 import { GridFSBucket } from './gridfs';
 import { GridFSBucketReadStream } from './gridfs/download';
 import { GridFSBucketWriteStream } from './gridfs/upload';
@@ -36,7 +37,11 @@ export {
   Timestamp,
   UUID
 } from './bson';
-export { AnyBulkWriteOperation, BulkWriteOptions, MongoBulkWriteError } from './bulk/common';
+export {
+  type AnyBulkWriteOperation,
+  type BulkWriteOptions,
+  MongoBulkWriteError
+} from './bulk/common';
 export { ClientEncryption } from './client-side-encryption/client_encryption';
 export { ChangeStreamCursor } from './cursor/change_stream_cursor';
 export {
@@ -66,6 +71,7 @@ export {
   MongoNetworkTimeoutError,
   MongoNotConnectedError,
   MongoOIDCError,
+  MongoOperationTimeoutError,
   MongoParseError,
   MongoRuntimeError,
   MongoServerClosedError,
@@ -90,6 +96,7 @@ export {
   ClientSession,
   Collection,
   Db,
+  ExplainableCursor,
   FindCursor,
   GridFSBucket,
   GridFSBucketReadStream,
@@ -108,7 +115,7 @@ export { AutoEncryptionLoggerLevel } from './client-side-encryption/auto_encrypt
 export { GSSAPICanonicalizationValue } from './cmap/auth/gssapi';
 export { AuthMechanism } from './cmap/auth/providers';
 export { Compressor } from './cmap/wire_protocol/compression';
-export { CURSOR_FLAGS } from './cursor/abstract_cursor';
+export { CURSOR_FLAGS, CursorTimeoutMode } from './cursor/abstract_cursor';
 export { MongoErrorLabel } from './error';
 export { ExplainVerbosity } from './explain';
 export { ServerApiVersion } from './mongo_client';
@@ -358,6 +365,7 @@ export type {
   CursorStreamOptions
 } from './cursor/abstract_cursor';
 export type {
+  CursorTimeoutContext,
   InitialCursorResponse,
   InternalAbstractCursorOptions
 } from './cursor/abstract_cursor';
@@ -566,7 +574,13 @@ export type {
   RTTSampler,
   ServerMonitoringMode
 } from './sdam/monitor';
-export type { Server, ServerEvents, ServerOptions, ServerPrivate } from './sdam/server';
+export type {
+  Server,
+  ServerCommandOptions,
+  ServerEvents,
+  ServerOptions,
+  ServerPrivate
+} from './sdam/server';
 export type {
   ServerDescription,
   ServerDescriptionOptions,
@@ -597,7 +611,15 @@ export type {
   WithTransactionCallback
 } from './sessions';
 export type { Sort, SortDirection, SortDirectionForCmd, SortForCmd } from './sort';
-export type { Timeout } from './timeout';
+export type {
+  CSOTTimeoutContext,
+  CSOTTimeoutContextOptions,
+  LegacyTimeoutContext,
+  LegacyTimeoutContextOptions,
+  Timeout,
+  TimeoutContext,
+  TimeoutContextOptions
+} from './timeout';
 export type { Transaction, TransactionOptions, TxnState } from './transactions';
 export type {
   BufferPool,

package/src/mongo_client.ts

@@ -130,7 +130,10 @@ export type SupportedNodeConnectionOptions = SupportedTLSConnectionOptions &
 export interface MongoClientOptions extends BSONSerializeOptions, SupportedNodeConnectionOptions {
   /** Specifies the name of the replica set, if the mongod is a member of a replica set. */
   replicaSet?: string;
-  /** @internal TODO(NODE-5688): This option is in development and currently has no behaviour.  */
+  /**
+   * @experimental
+   * Specifies the time an operation will run until it throws a timeout error
+   */
   timeoutMS?: number;
   /** Enables or disables TLS/SSL for the connection. */
   tls?: boolean;
@@ -482,6 +485,10 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
     return this.s.bsonOptions;
   }
 
+  get timeoutMS(): number | undefined {
+    return this.s.options.timeoutMS;
+  }
+
   /**
    * Executes a client bulk write operation, available on server 8.0+.
    * @param models - The client bulk write models.
@@ -508,6 +515,13 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
   /**
    * Connect to MongoDB using a url
    *
+   * @remarks
+   * Calling `connect` is optional since the first operation you perform will call `connect` if it's needed.
+   * `timeoutMS` will bound the time any operation can take before throwing a timeout error.
+   * However, when the operation being run is automatically connecting your `MongoClient` the `timeoutMS` will not apply to the time taken to connect the MongoClient.
+   * This means the time to setup the `MongoClient` does not count against `timeoutMS`.
+   * If you are using `timeoutMS` we recommend connecting your client explicitly in advance of any operation to avoid this inconsistent execution time.
+   *
    * @see docs.mongodb.org/manual/reference/connection-string/
    */
   async connect(): Promise<this> {
@@ -688,7 +702,7 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
 
     // Default to db from connection string if not provided
     if (!dbName) {
-      dbName = this.options.dbName;
+      dbName = this.s.options.dbName;
     }
 
     // Copy the options and add out internal override of the not shared flag
@@ -705,6 +719,13 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
    * Connect to MongoDB using a url
    *
    * @remarks
+   * Calling `connect` is optional since the first operation you perform will call `connect` if it's needed.
+   * `timeoutMS` will bound the time any operation can take before throwing a timeout error.
+   * However, when the operation being run is automatically connecting your `MongoClient` the `timeoutMS` will not apply to the time taken to connect the MongoClient.
+   * This means the time to setup the `MongoClient` does not count against `timeoutMS`.
+   * If you are using `timeoutMS` we recommend connecting your client explicitly in advance of any operation to avoid this inconsistent execution time.
+   *
+   * @remarks
    * The programmatically provided options take precedence over the URI options.
    *
    * @see https://www.mongodb.com/docs/manual/reference/connection-string/
@@ -789,6 +810,58 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
    * - The first is to provide the schema that may be defined for all the data within the current cluster
    * - The second is to override the shape of the change stream document entirely, if it is not provided the type will default to ChangeStreamDocument of the first argument
    *
+   * @remarks
+   * When `timeoutMS` is configured for a change stream, it will have different behaviour depending
+   * on whether the change stream is in iterator mode or emitter mode. In both cases, a change
+   * stream will time out if it does not receive a change event within `timeoutMS` of the last change
+   * event.
+   *
+   * Note that if a change stream is consistently timing out when watching a collection, database or
+   * client that is being changed, then this may be due to the server timing out before it can finish
+   * processing the existing oplog. To address this, restart the change stream with a higher
+   * `timeoutMS`.
+   *
+   * If the change stream times out the initial aggregate operation to establish the change stream on
+   * the server, then the client will close the change stream. If the getMore calls to the server
+   * time out, then the change stream will be left open, but will throw a MongoOperationTimeoutError
+   * when in iterator mode and emit an error event that returns a MongoOperationTimeoutError in
+   * emitter mode.
+   *
+   * To determine whether or not the change stream is still open following a timeout, check the
+   * {@link ChangeStream.closed} getter.
+   *
+   * @example
+   * In iterator mode, if a next() call throws a timeout error, it will attempt to resume the change stream.
+   * The next call can just be retried after this succeeds.
+   * ```ts
+   * const changeStream = collection.watch([], { timeoutMS: 100 });
+   * try {
+   *     await changeStream.next();
+   * } catch (e) {
+   *     if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
+   *       await changeStream.next();
+   *     }
+   *     throw e;
+   * }
+   * ```
+   *
+   * @example
+   * In emitter mode, if the change stream goes `timeoutMS` without emitting a change event, it will
+   * emit an error event that returns a MongoOperationTimeoutError, but will not close the change
+   * stream unless the resume attempt fails. There is no need to re-establish change listeners as
+   * this will automatically continue emitting change events once the resume attempt completes.
+   *
+   * ```ts
+   * const changeStream = collection.watch([], { timeoutMS: 100 });
+   * changeStream.on('change', console.log);
+   * changeStream.on('error', e => {
+   *     if (e instanceof MongoOperationTimeoutError && !changeStream.closed) {
+   *         // do nothing
+   *     } else {
+   *         changeStream.close();
+   *     }
+   * });
+   * ```
    * @param pipeline - An array of {@link https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/|aggregation pipeline stages} through which to pass change stream documents. This allows for filtering (using $match) and manipulating the change stream documents.
    * @param options - Optional settings for the command
    * @typeParam TSchema - Type of the data being detected by the change stream
@@ -952,6 +1025,5 @@ export interface MongoOptions
    * TODO: NODE-5671 - remove internal flag
    */
   mongodbLogPath?: 'stderr' | 'stdout' | MongoDBLogWritable;
-  /** @internal TODO(NODE-5688): make this public */
   timeoutMS?: number;
 }