POC

Author: baileympearson

src/explain.ts

@@ -19,10 +19,18 @@ export type ExplainVerbosity = string;
  */
 export type ExplainVerbosityLike = ExplainVerbosity | boolean;
 
+/**
+ * @public
+ */
+export interface ExplainCommandOptions {
+  verbosity: ExplainVerbosityLike;
+  maxTimeMS?: number;
+}
+
 /** @public */
 export interface ExplainOptions {
   /** Specifies the verbosity mode for the explain output. */
-  explain?: ExplainVerbosityLike;
+  explain?: ExplainVerbosityLike | ExplainCommandOptions;
 }
 
 /** @internal */
@@ -39,14 +47,34 @@ export class Explain {
     }
   }
 
-  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');
+    if (typeof explain === 'object') {
+      const { verbosity } = explain;
+      return new Explain(verbosity);
+    }
+
+    throw new MongoInvalidArgumentError(
+      'Field "explain" must be a string, a boolean or an ExplainCommandOptions object.'
+    );
+  }
+}
+
+export class ExplainCommandOptions2 {
+  private constructor(
+    public readonly explain: Explain,
+    public readonly maxTimeMS: number | undefined
+  ) {}
+
+  static fromOptions(options: ExplainOptions = {}): ExplainCommandOptions2 | undefined {
+    const explain = Explain.fromOptions(options);
+    const maxTimeMS = typeof options.explain === 'object' ? options.explain.maxTimeMS : undefined;
+
+    return explain ? new ExplainCommandOptions2(explain, maxTimeMS) : undefined;
   }
 }

src/operations/command.ts

@@ -1,7 +1,7 @@
 import type { BSONSerializeOptions, Document } from '../bson';
 import { type MongoDBResponseConstructor } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError } from '../error';
-import { Explain, type ExplainOptions } from '../explain';
+import { ExplainCommandOptions2, type ExplainOptions } from '../explain';
 import { ReadConcern } from '../read_concern';
 import type { ReadPreference } from '../read_preference';
 import type { Server } from '../sdam/server';
@@ -72,7 +72,7 @@ export abstract class CommandOperation<T> extends AbstractOperation<T> {
   override options: CommandOperationOptions;
   readConcern?: ReadConcern;
   writeConcern?: WriteConcern;
-  explain?: Explain;
+  explain?: ExplainCommandOptions2;
 
   constructor(parent?: OperationParent, options?: CommandOperationOptions) {
     super(options);
@@ -94,7 +94,7 @@ export abstract class CommandOperation<T> extends AbstractOperation<T> {
     this.writeConcern = WriteConcern.fromOptions(options);
 
     if (this.hasAspect(Aspect.EXPLAINABLE)) {
-      this.explain = Explain.fromOptions(options);
+      this.explain = ExplainCommandOptions2.fromOptions(options);
     } else if (options?.explain != null) {
       throw new MongoInvalidArgumentError(`Option "explain" is not supported on this command`);
     }

src/utils.ts

@@ -25,7 +25,7 @@ import {
   MongoParseError,
   MongoRuntimeError
 } from './error';
-import type { Explain } from './explain';
+import type { ExplainCommandOptions2, ExplainVerbosity } from './explain';
 import type { MongoClient } from './mongo_client';
 import type { CommandOperationOptions, OperationParent } from './operations/command';
 import type { Hint, OperationOptions } from './operations/operation';
@@ -252,12 +252,27 @@ 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,
+  explainOptions: ExplainCommandOptions2
+): {
+  explain: Document;
+  verbosity: ExplainVerbosity;
+  maxTimeMS?: number;
+} {
+  type ExplainCommand = ReturnType<typeof decorateWithExplain>;
+  if ('explain' in command && 'verbosity' in command) {
+    return command as ExplainCommand;
   }
 
-  return { explain: command, verbosity: explain.verbosity };
+  const { explain, maxTimeMS } = explainOptions;
+  const { verbosity } = explain;
+
+  const baseCommand: ExplainCommand = { explain: command, verbosity };
+  if (typeof maxTimeMS === 'number') {
+    baseCommand.maxTimeMS = maxTimeMS;
+  }
+  return baseCommand;
 }
 
 /**