deprecate legacy timeout options; add logic to prefer timeoutMS

Author: W-A-James

src/connection_string.ts

@@ -1092,6 +1092,7 @@ export const OPTIONS = {
     type: 'string'
   },
   socketTimeoutMS: {
+    deprecated: 'Please use timeoutMS instead',
     default: 0,
     type: 'uint'
   },
@@ -1162,6 +1163,7 @@ export const OPTIONS = {
     }
   },
   waitQueueTimeoutMS: {
+    deprecated: 'Please use timeoutMS instead',
     default: 0,
     type: 'uint'
   },

src/cursor/abstract_cursor.ts

@@ -84,6 +84,7 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
   /**
    * When applicable `maxTimeMS` controls the amount of time the initial command
    * that constructs a cursor should take. (ex. find, aggregate, listCollections)
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead.
    */
   maxTimeMS?: number;
   /**
@@ -721,6 +722,7 @@ export abstract class AbstractCursor<
    * Set a maxTimeMS on the cursor query, allowing for hard timeout limits on queries (Only supported on MongoDB 2.6 or higher)
    *
    * @param value - Number of milliseconds to wait before aborting the query.
+   * @deprecated Will be removed in the next major version. Please use the timeoutMS option instead.
    */
   maxTimeMS(value: number): this {
     this.throwIfInitialized();

src/cursor/find_cursor.ts

@@ -333,6 +333,7 @@ export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
    * Set a maxTimeMS on the cursor query, allowing for hard timeout limits on queries (Only supported on MongoDB 2.6 or higher)
    *
    * @param value - Number of milliseconds to wait before aborting the query.
+   *@deprecated Will be removed in the next major version. Please use timeoutMS instead.
    */
   override maxTimeMS(value: number): this {
     this.throwIfInitialized();

src/cursor/run_command_cursor.ts

@@ -48,6 +48,7 @@ export class RunCommandCursor extends AbstractCursor {
   /**
    * Controls the `getMore.maxTimeMS` field. Only valid when cursor is tailable await
    * @param maxTimeMS - the number of milliseconds to wait for new data
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead.
    */
   public setMaxTimeMS(maxTimeMS: number): this {
     this.getMoreOptions.maxAwaitTimeMS = maxTimeMS;
@@ -56,7 +57,7 @@ export class RunCommandCursor extends AbstractCursor {
 
   /**
    * Controls the `getMore.batchSize` field
-   * @param maxTimeMS - the number documents to return in the `nextBatch`
+   * @param batchSize - the number documents to return in the `nextBatch`
    */
   public setBatchSize(batchSize: number): this {
     this.getMoreOptions.batchSize = batchSize;
@@ -82,7 +83,8 @@ export class RunCommandCursor extends AbstractCursor {
     );
   }
 
-  /** Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document */
+  /** Unsupported for RunCommandCursor: maxTimeMS must be configured directly on command document
+   * @deprecated Will be removed in the next major version. */
   public override maxTimeMS(_: number): never {
     throw new MongoAPIError(
       'maxTimeMS must be configured on the command document directly, to configure getMore.maxTimeMS use cursor.setMaxTimeMS()'

src/explain.ts

@@ -24,7 +24,8 @@ export type ExplainVerbosityLike = ExplainVerbosity | boolean;
 export interface ExplainCommandOptions {
   /** The explain verbosity for the command. */
   verbosity: ExplainVerbosity;
-  /** The maxTimeMS setting for the command. */
+  /** The maxTimeMS setting for the command.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead.*/
   maxTimeMS?: number;
 }
 

src/mongo_client.ts

@@ -152,7 +152,8 @@ export interface MongoClientOptions extends BSONSerializeOptions, SupportedNodeC
   tlsInsecure?: boolean;
   /** The time in milliseconds to attempt a connection before timing out. */
   connectTimeoutMS?: number;
-  /** The time in milliseconds to attempt a send or receive on a socket before the attempt times out. */
+  /** The time in milliseconds to attempt a send or receive on a socket before the attempt times out.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead */
   socketTimeoutMS?: number;
   /** An array or comma-delimited string of compressors to enable network compression for communication between this client and a mongod/mongos instance. */
   compressors?: CompressorName[] | string;
@@ -176,7 +177,8 @@ export interface MongoClientOptions extends BSONSerializeOptions, SupportedNodeC
   maxConnecting?: number;
   /** The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. */
   maxIdleTimeMS?: number;
-  /** The maximum time in milliseconds that a thread can wait for a connection to become available. */
+  /** The maximum time in milliseconds that a thread can wait for a connection to become available.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead */
   waitQueueTimeoutMS?: number;
   /** Specify a read concern for the collection (only MongoDB 3.2 or higher supported) */
   readConcern?: ReadConcernLike;

src/operations/aggregate.ts

@@ -26,7 +26,8 @@ export interface AggregateOptions extends Omit<CommandOperationOptions, 'explain
   bypassDocumentValidation?: boolean;
   /** Return the query as cursor, on 2.6 \> it returns as a real cursor on pre 2.6 it returns as an emulated cursor. */
   cursor?: Document;
-  /** specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point. */
+  /** specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead.*/
   maxTimeMS?: number;
   /** The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. */
   maxAwaitTimeMS?: number;

src/operations/command.ts

@@ -40,6 +40,8 @@ export interface CommandOperationOptions
   readConcern?: ReadConcernLike;
   /** Collation */
   collation?: CollationOptions;
+  /**
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead. */
   maxTimeMS?: number;
   /**
    * Comment to apply to the operation.

src/operations/count.ts

@@ -13,7 +13,8 @@ export interface CountOptions extends CommandOperationOptions {
   skip?: number;
   /** The maximum amounts to count before aborting. */
   limit?: number;
-  /** Number of milliseconds to wait before aborting the query. */
+  /** Number of milliseconds to wait before aborting the query.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead. */
   maxTimeMS?: number;
   /** An index name hint for the query. */
   hint?: string | Document;

src/operations/estimated_document_count.ts

@@ -12,6 +12,7 @@ export interface EstimatedDocumentCountOptions extends CommandOperationOptions {
    * The maximum amount of time to allow the operation to run.
    *
    * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   *@deprecated Will be removed in the next major version. Please use timeoutMS instead.
    */
   maxTimeMS?: number;
 }

src/operations/find.ts

@@ -48,7 +48,8 @@ export interface FindOptions<TSchema extends Document = Document>
   min?: Document;
   /** The exclusive upper bound for a specific index */
   max?: Document;
-  /** Number of milliseconds to wait before aborting the query. */
+  /** Number of milliseconds to wait before aborting the query.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead. */
   maxTimeMS?: number;
   /** The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. Requires `tailable` and `awaitData` to be true */
   maxAwaitTimeMS?: number;
@@ -77,7 +78,6 @@ export interface FindOptions<TSchema extends Document = Document>
    * @deprecated This API is deprecated in favor of `collection.find().explain()`.
    */
   explain?: ExplainOptions['explain'];
-  /** @internal*/
   timeoutMode?: CursorTimeoutMode;
 }
 

src/operations/get_more.ts

@@ -17,7 +17,7 @@ export interface GetMoreOptions extends OperationOptions {
    * getMore only supports 'comment' in server versions 4.4 and above.
    */
   comment?: unknown;
-  /** Number of milliseconds to wait before aborting the query. */
+  /** Number of milliseconds to wait before aborting the query.
   maxTimeMS?: number;
   /** TODO(NODE-4413): Address bug with maxAwaitTimeMS not being passed in from the cursor correctly */
   maxAwaitTimeMS?: number;

src/sessions.ts

@@ -487,13 +487,29 @@ export class ClientSession
       maxTimeMS?: number;
     } = { commitTransaction: 1 };
 
+    const timeoutMS =
+      typeof options?.timeoutMS === 'number'
+        ? options.timeoutMS
+        : typeof this.timeoutMS === 'number'
+          ? this.timeoutMS
+          : null;
+
     const wc = this.transaction.options.writeConcern ?? this.clientOptions?.writeConcern;
     if (wc != null) {
-      WriteConcern.apply(command, { wtimeoutMS: 10000, w: 'majority', ...wc });
+      if (timeoutMS == null && this.timeoutContext == null) {
+        WriteConcern.apply(command, { wtimeoutMS: 10000, w: 'majority', ...wc });
+      } else {
+        WriteConcern.apply(command, { w: 'majority', ...wc, wtimeoutMS: undefined });
+      }
     }
 
     if (this.transaction.state === TxnState.TRANSACTION_COMMITTED || this.commitAttempted) {
       WriteConcern.apply(command, { wtimeoutMS: 10000, ...wc, w: 'majority' });
+      if (timeoutMS == null && this.timeoutContext == null) {
+        WriteConcern.apply(command, { wtimeoutMS: 10000, ...wc, w: 'majority' });
+      } else {
+        WriteConcern.apply(command, { w: 'majority', ...wc, wtimeoutMS: undefined });
+      }
     }
 
     if (typeof this.transaction.options.maxTimeMS === 'number') {
@@ -510,13 +526,6 @@ export class ClientSession
       bypassPinningCheck: true
     });
 
-    const timeoutMS =
-      typeof options?.timeoutMS === 'number'
-        ? options.timeoutMS
-        : typeof this.timeoutMS === 'number'
-          ? this.timeoutMS
-          : null;
-
     const timeoutContext =
       this.timeoutContext ??
       (typeof timeoutMS === 'number'
@@ -616,21 +625,6 @@ export class ClientSession
       recoveryToken?: Document;
     } = { abortTransaction: 1 };
 
-    const wc = this.transaction.options.writeConcern ?? this.clientOptions?.writeConcern;
-    if (wc != null) {
-      WriteConcern.apply(command, { wtimeoutMS: 10000, w: 'majority', ...wc });
-    }
-
-    if (this.transaction.recoveryToken) {
-      command.recoveryToken = this.transaction.recoveryToken;
-    }
-
-    const operation = new RunAdminCommandOperation(command, {
-      session: this,
-      readPreference: ReadPreference.primary,
-      bypassPinningCheck: true
-    });
-
     const timeoutMS =
       typeof options?.timeoutMS === 'number'
         ? options.timeoutMS
@@ -649,6 +643,21 @@ export class ClientSession
           })
         : null;
 
+    const wc = this.transaction.options.writeConcern ?? this.clientOptions?.writeConcern;
+    if (wc != null && timeoutMS == null) {
+      WriteConcern.apply(command, { wtimeoutMS: 10000, w: 'majority', ...wc });
+    }
+
+    if (this.transaction.recoveryToken) {
+      command.recoveryToken = this.transaction.recoveryToken;
+    }
+
+    const operation = new RunAdminCommandOperation(command, {
+      session: this,
+      readPreference: ReadPreference.primary,
+      bypassPinningCheck: true
+    });
+
     try {
       await executeOperation(this.client, operation, timeoutContext);
       this.unpin();

src/utils.ts

@@ -516,20 +516,31 @@ export function resolveOptions<T extends CommandOperationOptions>(
 ): T {
   const result: T = Object.assign({}, options, resolveBSONOptions(options, parent));
 
+  const timeoutMS = options?.timeoutMS ?? parent?.timeoutMS;
   // Users cannot pass a readConcern/writeConcern to operations in a transaction
   const session = options?.session;
+
   if (!session?.inTransaction()) {
     const readConcern = ReadConcern.fromOptions(options) ?? parent?.readConcern;
     if (readConcern) {
       result.readConcern = readConcern;
     }
 
-    const writeConcern = WriteConcern.fromOptions(options) ?? parent?.writeConcern;
+    let writeConcern = WriteConcern.fromOptions(options) ?? parent?.writeConcern;
     if (writeConcern) {
+      if (timeoutMS != null) {
+        writeConcern = WriteConcern.fromOptions({
+          ...writeConcern,
+          wtimeout: undefined,
+          wtimeoutMS: undefined
+        });
+      }
       result.writeConcern = writeConcern;
     }
   }
 
+  result.timeoutMS = timeoutMS;
+
   const readPreference = ReadPreference.fromOptions(options) ?? parent?.readPreference;
   if (readPreference) {
     result.readPreference = readPreference;
@@ -542,8 +553,6 @@ export function resolveOptions<T extends CommandOperationOptions>(
     );
   }
 
-  result.timeoutMS = options?.timeoutMS ?? parent?.timeoutMS;
-
   return result;
 }
 

src/write_concern.ts

@@ -15,7 +15,8 @@ export interface WriteConcernOptions {
 export interface WriteConcernSettings {
   /** The write concern */
   w?: W;
-  /** The write concern timeout */
+  /** The write concern timeout
+   * @deprecated Will be removed in the next major version. Please use timeoutMS */
   wtimeoutMS?: number;
   /** The journal write concern */
   journal?: boolean;
@@ -65,7 +66,8 @@ export class WriteConcern {
   readonly w?: W;
   /** Request acknowledgment that the write operation has been written to the on-disk journal */
   readonly journal?: boolean;
-  /** Specify a time limit to prevent write operations from blocking indefinitely */
+  /** Specify a time limit to prevent write operations from blocking indefinitely
+   * @deprecated Will be removed in the next major version. Please use timeoutMS */
   readonly wtimeoutMS?: number;
   /**
    * Specify a time limit to prevent write operations from blocking indefinitely.