feat(NODE-6446): deprecate legacy timeout options (mongodb#4279)

Co-authored-by: Neal Beeken <[email protected]>

Author: 2 people

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/aggregation_cursor.ts

@@ -75,12 +75,14 @@ export class AggregationCursor<TSchema = any> extends ExplainableCursor<TSchema>
       ...this.cursorOptions,
       session
     };
-    try {
-      validateExplainTimeoutOptions(options, Explain.fromOptions(options));
-    } catch {
-      throw new MongoAPIError(
-        'timeoutMS cannot be used with explain when explain is specified in aggregateOptions'
-      );
+    if (options.explain) {
+      try {
+        validateExplainTimeoutOptions(options, Explain.fromOptions(options));
+      } catch {
+        throw new MongoAPIError(
+          'timeoutMS cannot be used with explain when explain is specified in aggregateOptions'
+        );
+      }
     }
 
     const aggregateOperation = new AggregateOperation(this.namespace, this.pipeline, options);

src/cursor/find_cursor.ts

@@ -75,12 +75,14 @@ export class FindCursor<TSchema = any> extends ExplainableCursor<TSchema> {
       session
     };
 
-    try {
-      validateExplainTimeoutOptions(options, Explain.fromOptions(options));
-    } catch {
-      throw new MongoAPIError(
-        'timeoutMS cannot be used with explain when explain is specified in findOptions'
-      );
+    if (options.explain) {
+      try {
+        validateExplainTimeoutOptions(options, Explain.fromOptions(options));
+      } catch {
+        throw new MongoAPIError(
+          'timeoutMS cannot be used with explain when explain is specified in findOptions'
+        );
+      }
     }
 
     const findOperation = new FindOperation(this.namespace, this.cursorFilter, options);

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,10 @@ 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/mongo_client.ts

@@ -152,7 +152,10 @@ 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 +179,10 @@ 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,10 @@ 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,10 @@ export interface CommandOperationOptions
   readConcern?: ReadConcernLike;
   /** Collation */
   collation?: CollationOptions;
+  /**
+   * maxTimeMS is a server-side time limit in milliseconds for processing an operation.
+   * @deprecated Will be removed in the next major version. Please use timeoutMS instead.
+   */
   maxTimeMS?: number;
   /**
    * Comment to apply to the operation.
@@ -97,7 +101,7 @@ export abstract class CommandOperation<T> extends AbstractOperation<T> {
 
     if (this.hasAspect(Aspect.EXPLAINABLE)) {
       this.explain = Explain.fromOptions(options);
-      validateExplainTimeoutOptions(this.options, this.explain);
+      if (this.explain) validateExplainTimeoutOptions(this.options, this.explain);
     } else if (options?.explain != null) {
       throw new MongoInvalidArgumentError(`Option "explain" is not supported on this command`);
     }

src/operations/count.ts

@@ -13,7 +13,10 @@ 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;
 }