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