start API docs

Author: W-A-James

src/collection.ts

@@ -115,7 +115,7 @@ export interface CollectionOptions extends BSONSerializeOptions, WriteConcernOpt
   readConcern?: ReadConcernLike;
   /** The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST). */
   readPreference?: ReadPreferenceLike;
-  /** @internal TODO(NODE-5688): make this public */
+  /** Specifies the time an operation will run until it throws a timeout error */
   timeoutMS?: number;
 }
 
@@ -262,7 +262,6 @@ export class Collection<TSchema extends Document = Document> {
     this.s.collectionHint = normalizeHintField(v);
   }
 
-  /** @internal */
   get timeoutMS(): number | undefined {
     return this.s.options.timeoutMS;
   }

src/cursor/abstract_cursor.ts

@@ -61,15 +61,36 @@ export interface CursorStreamOptions {
 /** @public */
 export type CursorFlag = (typeof CURSOR_FLAGS)[number];
 
-/** @public*/
+/** @public */
 export const CursorTimeoutMode = Object.freeze({
   ITERATION: 'iteration',
   LIFETIME: 'cursorLifetime'
 } as const);
 
 /** @public
- * TODO(NODE-5688): Document and release
- * */
+ * Specifies how `timeoutMS` is applied to the cursor. Can be either `'cursorLifeTime'` or `'iteration'`
+ * When set to `'iteration'`, the deadline specified by `timeoutMS` applies to each call of
+ * `cursor.next()`.
+ * When set to `'cursorLifetime'`, the deadline applies to the life of the entire cursor.
+ *
+ * @example
+ * # Example showing use of `'iteration'`
+ * ```ts
+ * const cursor = collection.find({}, {timeoutMS: 100, timeoutMode: 'iteration'});
+ * for await (const doc of cursor) {
+ *  // process doc
+ *  // This will throw a timeout error if any of the iterator's `next()` calls takes more than 100ms, but
+ * will continue to iterate successfully otherwise, regardless of the number of batches.
+ * }
+ * ```
+ *
+ * # Example showing use of `'cursorLifetime'`
+ *
+ * ```ts
+ * const cursor = collection.find({}, { timeoutMS: 1000, timeoutMode: 'cursorLifetime' });
+ * const docs = await cursor.toArray(); // This entire line will throw a timeout error if all batches are not fetched and returned within 1000ms.
+ * ```
+ */
 export type CursorTimeoutMode = (typeof CursorTimeoutMode)[keyof typeof CursorTimeoutMode];
 
 /** @public */
@@ -116,9 +137,32 @@ export interface AbstractCursorOptions extends BSONSerializeOptions {
    */
   awaitData?: boolean;
   noCursorTimeout?: boolean;
-  /** @internal TODO(NODE-5688): make this public */
+  /** Specifies the time an operation will run until it throws a timeout error. See {@link AbstractCursorOptions.timeoutMode} for more details. */
   timeoutMS?: number;
-  /** @internal TODO(NODE-5688): make this public */
+  /**
+   * Specifies how `timeoutMS` is applied to the cursor. Can be either `'cursorLifeTime'` or `'iteration'`
+   * When set to `'iteration'`, the deadline specified by `timeoutMS` applies to each call of
+   * `cursor.next()`.
+   * When set to `'cursorLifetime'`, the deadline applies to the life of the entire cursor.
+   *
+   * @example
+   * # Example showing use of `'iteration'`
+   * ```ts
+   * const cursor = collection.find({}, {timeoutMS: 100, timeoutMode: 'iteration'});
+   * for await (const doc of cursor) {
+   *  // process doc
+   *  // This will throw a timeout error if any of the iterator's `next()` calls takes more than 100ms, but
+   * will continue to iterate successfully otherwise, regardless of the number of batches.
+   * }
+   * ```
+   *
+   * # Example showing use of `'cursorLifetime'`
+   *
+   * ```ts
+   * const cursor = collection.find({}, { timeoutMS: 1000, timeoutMode: 'cursorLifetime' });
+   * const docs = await cursor.toArray(); // This entire line will throw a timeout error if all batches are not fetched and returned within 1000ms.
+   * ```
+   */
   timeoutMode?: CursorTimeoutMode;
 
   /**

src/db.ts

@@ -97,7 +97,7 @@ export interface DbOptions extends BSONSerializeOptions, WriteConcernOptions {
   readConcern?: ReadConcern;
   /** Should retry failed writes */
   retryWrites?: boolean;
-  /** @internal TODO(NODE-5688): make this public */
+  /** Specifies the time an operation will run until it throws a timeout error */
   timeoutMS?: number;
 }
 
@@ -222,7 +222,6 @@ export class Db {
     return this.s.namespace.toString();
   }
 
-  /** @internal */
   get timeoutMS(): number | undefined {
     return this.s.options?.timeoutMS;
   }

src/error.ts

@@ -865,7 +865,6 @@ export class MongoUnexpectedServerResponseError extends MongoRuntimeError {
  * @category Error
  *
  * This error is thrown when an operation could not be completed within the specified `timeoutMS`.
- * TODO(NODE-5688): expand this documentation.
  *
  * @example
  * ```ts

src/gridfs/index.ts

@@ -38,7 +38,7 @@ export interface GridFSBucketOptions extends WriteConcernOptions {
   chunkSizeBytes?: number;
   /** Read preference to be passed to read operations */
   readPreference?: ReadPreference;
-  /** @internal TODO(NODE-5688): make this public */
+  /** Specifies the time an operation will run until it throws a timeout error */
   timeoutMS?: number;
 }
 

src/mongo_client.ts

@@ -130,7 +130,7 @@ 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.  */
+  /** 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;
@@ -488,7 +488,6 @@ export class MongoClient extends TypedEventEmitter<MongoClientEvents> implements
     return this.s.bsonOptions;
   }
 
-  /** @internal */
   get timeoutMS(): number | undefined {
     return this.options.timeoutMS;
   }
@@ -977,6 +976,5 @@ export interface MongoOptions
    * TODO: NODE-5671 - remove internal flag
    */
   mongodbLogPath?: 'stderr' | 'stdout' | MongoDBLogWritable;
-  /** @internal TODO(NODE-5688): make this public */
   timeoutMS?: number;
 }

src/operations/indexes.ts

@@ -361,8 +361,6 @@ export class DropIndexOperation extends CommandOperation<Document> {
 
 /** @public */
 export type ListIndexesOptions = AbstractCursorOptions & {
-  /** @internal TODO(NODE-5688): make this public */
-  timeoutMode?: CursorTimeoutMode;
   /** @internal */
   omitMaxTimeMS?: boolean;
 };

src/operations/operation.ts

@@ -35,7 +35,7 @@ export interface OperationOptions extends BSONSerializeOptions {
   /** @internal Hint to `executeOperation` to omit maxTimeMS */
   omitMaxTimeMS?: boolean;
 
-  /** @internal TODO(NODE-5688): make this public */
+  /** Specifies the time an operation will run until it throws a timeout error */
   timeoutMS?: number;
 }