feat(NODE-6342): support maxTimeMS for explain commands (#4207)

src/cursor/aggregation_cursor.ts

@@ -1,5 +1,5 @@
 import type { Document } from '../bson';
-import type { ExplainVerbosityLike } from '../explain';
+import type { ExplainCommandOptions, ExplainVerbosityLike } from '../explain';
 import type { MongoClient } from '../mongo_client';
 import { AggregateOperation, type AggregateOptions } from '../operations/aggregate';
 import { executeOperation } from '../operations/execute_operation';
@@ -66,7 +66,7 @@ export class AggregationCursor<TSchema = any> extends AbstractCursor<TSchema> {
   }
 
   /** Execute the explain for the cursor */
-  async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
+  async explain(verbosity?: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document> {
     return (
       await executeOperation(
         this.client,

src/cursor/find_cursor.ts

@@ -1,7 +1,7 @@
 import { type Document } from '../bson';
 import { CursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError, MongoTailableCursorError } from '../error';
-import { type ExplainVerbosityLike } from '../explain';
+import { type ExplainCommandOptions, type ExplainVerbosityLike } from '../explain';
 import type { MongoClient } from '../mongo_client';
 import type { CollationOptions } from '../operations/command';
 import { CountOperation, type CountOptions } from '../operations/count';
@@ -133,7 +133,7 @@ export class FindCursor<TSchema = any> extends AbstractCursor<TSchema> {
   }
 
   /** Execute the explain for the cursor */
-  async explain(verbosity?: ExplainVerbosityLike): Promise<Document> {
+  async explain(verbosity?: ExplainVerbosityLike | ExplainCommandOptions): Promise<Document> {
     return (
       await executeOperation(
         this.client,

src/explain.ts

@@ -1,5 +1,3 @@
-import { MongoInvalidArgumentError } from './error';
-
 /** @public */
 export const ExplainVerbosity = Object.freeze({
   queryPlanner: 'queryPlanner',
@@ -19,33 +17,72 @@ export type ExplainVerbosity = string;
 export type ExplainVerbosityLike = ExplainVerbosity | boolean;
 
 /** @public */
+export interface ExplainCommandOptions {
+  /** The explain verbosity for the command. */
+  verbosity: ExplainVerbosity;
+  /** The maxTimeMS setting for the command. */
+  maxTimeMS?: number;
+}
+
+/**
+ * @public
+ *
+ * When set, this configures an explain command.  Valid values are boolean (for legacy compatibility,
+ * see {@link ExplainVerbosityLike}), a string containing the explain verbosity, or an object containing the verbosity and
+ * an optional maxTimeMS.
+ *
+ * Examples of valid usage:
+ *
+ * ```typescript
+ * collection.find({ name: 'john doe' }, { explain: true });
+ * collection.find({ name: 'john doe' }, { explain: false });
+ * collection.find({ name: 'john doe' }, { explain: 'queryPlanner' });
+ * collection.find({ name: 'john doe' }, { explain: { verbosity: 'queryPlanner' } });
+ * ```
+ *
+ * maxTimeMS can be configured to limit the amount of time the server
+ * spends executing an explain by providing an object:
+ *
+ * ```typescript
+ * // limits the `explain` command to no more than 2 seconds
+ * collection.find({ name: 'john doe' }, {
+ *   explain:  {
+ *    verbosity: 'queryPlanner',
+ *    maxTimeMS: 2000
+ *  }
+ * });
+ * ```
+ */
 export interface ExplainOptions {
   /** Specifies the verbosity mode for the explain output. */
-  explain?: ExplainVerbosityLike;
+  explain?: ExplainVerbosityLike | ExplainCommandOptions;
 }
 
 /** @internal */
 export class Explain {
-  verbosity: ExplainVerbosity;
+  readonly verbosity: ExplainVerbosity;
+  readonly maxTimeMS?: number;
 
-  constructor(verbosity: ExplainVerbosityLike) {
+  private constructor(verbosity: ExplainVerbosityLike, maxTimeMS?: number) {
     if (typeof verbosity === 'boolean') {
       this.verbosity = verbosity
         ? ExplainVerbosity.allPlansExecution
         : ExplainVerbosity.queryPlanner;
     } else {
       this.verbosity = verbosity;
     }
+
+    this.maxTimeMS = maxTimeMS;
   }
 
-  static fromOptions(options?: ExplainOptions): Explain | undefined {
-    if (options?.explain == null) return;
+  static fromOptions({ explain }: ExplainOptions = {}): Explain | undefined {
+    if (explain == null) return;
 
-    const explain = options.explain;
     if (typeof explain === 'boolean' || typeof explain === 'string') {
       return new Explain(explain);
     }
 
-    throw new MongoInvalidArgumentError('Field "explain" must be a string or a boolean');
+    const { verbosity, maxTimeMS } = explain;
+    return new Explain(verbosity, maxTimeMS);
   }
 }

src/index.ts

@@ -368,7 +368,12 @@ export type { RunCursorCommandOptions } from './cursor/run_command_cursor';
 export type { DbOptions, DbPrivate } from './db';
 export type { Encrypter, EncrypterOptions } from './encrypter';
 export type { AnyError, ErrorDescription, MongoNetworkErrorOptions } from './error';
-export type { Explain, ExplainOptions, ExplainVerbosityLike } from './explain';
+export type {
+  Explain,
+  ExplainCommandOptions,
+  ExplainOptions,
+  ExplainVerbosityLike
+} from './explain';
 export type {
   GridFSBucketReadStreamOptions,
   GridFSBucketReadStreamOptionsWithRevision,

src/utils.ts

@@ -25,7 +25,7 @@ import {
   MongoParseError,
   MongoRuntimeError
 } from './error';
-import type { Explain } from './explain';
+import type { Explain, ExplainVerbosity } from './explain';
 import type { MongoClient } from './mongo_client';
 import type { CommandOperationOptions, OperationParent } from './operations/command';
 import type { Hint, OperationOptions } from './operations/operation';
@@ -251,12 +251,23 @@ export function decorateWithReadConcern(
  * @param command - the command on which to apply the explain
  * @param options - the options containing the explain verbosity
  */
-export function decorateWithExplain(command: Document, explain: Explain): Document {
-  if (command.explain) {
-    return command;
+export function decorateWithExplain(
+  command: Document,
+  explain: Explain
+): {
+  explain: Document;
+  verbosity: ExplainVerbosity;
+  maxTimeMS?: number;
+} {
+  type ExplainCommand = ReturnType<typeof decorateWithExplain>;
+  const { verbosity, maxTimeMS } = explain;
+  const baseCommand: ExplainCommand = { explain: command, verbosity };
+
+  if (typeof maxTimeMS === 'number') {
+    baseCommand.maxTimeMS = maxTimeMS;
   }
 
-  return { explain: command, verbosity: explain.verbosity };
+  return baseCommand;
 }
 
 /**

test/integration/crud/crud.prose.test.ts

@@ -1,7 +1,14 @@
 import { expect } from 'chai';
 import { once } from 'events';
 
-import { MongoBulkWriteError, type MongoClient, MongoServerError } from '../../mongodb';
+import { type CommandStartedEvent } from '../../../mongodb';
+import {
+  type Collection,
+  MongoBulkWriteError,
+  type MongoClient,
+  MongoServerError
+} from '../../mongodb';
+import { filterForCommands } from '../shared';
 
 describe('CRUD Prose Spec Tests', () => {
   let client: MongoClient;
@@ -143,4 +150,42 @@ describe('CRUD Prose Spec Tests', () => {
       }
     });
   });
+
+  describe('14. `explain` helpers allow users to specify `maxTimeMS`', function () {
+    let client: MongoClient;
+    const commands: CommandStartedEvent[] = [];
+    let collection: Collection;
+
+    beforeEach(async function () {
+      client = this.configuration.newClient({}, { monitorCommands: true });
+      await client.connect();
+
+      await client.db('explain-test').dropDatabase();
+      collection = await client.db('explain-test').createCollection('collection');
+
+      client.on('commandStarted', filterForCommands('explain', commands));
+      commands.length = 0;
+    });
+
+    afterEach(async function () {
+      await client.close();
+    });
+
+    it('sets maxTimeMS on explain commands, when specified', async function () {
+      await collection
+        .find(
+          { name: 'john doe' },
+          {
+            explain: {
+              maxTimeMS: 2000,
+              verbosity: 'queryPlanner'
+            }
+          }
+        )
+        .toArray();
+
+      const [{ command }] = commands;
+      expect(command).to.have.property('maxTimeMS', 2000);
+    });
+  });
 });