feat: add explain support for non-cursor commands

src/cmap/wire_protocol/write_command.ts

@@ -1,9 +1,11 @@
 import { MongoError } from '../../error';
-import { collectionNamespace, Callback } from '../../utils';
+import { collectionNamespace, Callback, decorateWithExplain } from '../../utils';
 import { command, CommandOptions } from './command';
 import type { Server } from '../../sdam/server';
 import type { Document, BSONSerializeOptions } from '../../bson';
 import type { WriteConcern } from '../../write_concern';
+import { Explain } from '../../explain';
+import type { ExplainOptions } from '../../operations/explainable_command';
 
 /** @public */
 export interface CollationOptions {
@@ -18,7 +20,7 @@ export interface CollationOptions {
 }
 
 /** @internal */
-export interface WriteCommandOptions extends BSONSerializeOptions, CommandOptions {
+export interface WriteCommandOptions extends BSONSerializeOptions, CommandOptions, ExplainOptions {
   ordered?: boolean;
   writeConcern?: WriteConcern;
   collation?: CollationOptions;
@@ -43,7 +45,7 @@ export function writeCommand(
   options = options || {};
   const ordered = typeof options.ordered === 'boolean' ? options.ordered : true;
   const writeConcern = options.writeConcern;
-  const writeCommand: Document = {};
+  let writeCommand: Document = {};
   writeCommand[type] = collectionNamespace(ns);
   writeCommand[opsField] = ops;
   writeCommand.ordered = ordered;
@@ -64,6 +66,15 @@ export function writeCommand(
     writeCommand.bypassDocumentValidation = options.bypassDocumentValidation;
   }
 
+  // If a command is to be explained, we need to reformat the command after
+  // the other command properties are specified.
+  if (options.explain !== undefined) {
+    const explain = Explain.fromOptions(options);
+    if (explain) {
+      writeCommand = decorateWithExplain(writeCommand, explain);
+    }
+  }
+
   const commandOptions = Object.assign(
     {
       checkKeys: type === 'insert',

src/cursor/cursor.ts

@@ -1307,10 +1307,11 @@ export class Cursor<
   explain(callback?: Callback): Promise<unknown> | void {
     // NOTE: the next line includes a special case for operations which do not
     //       subclass `CommandOperationV2`. To be removed asap.
-    if (this.operation && this.operation.cmd == null) {
-      this.operation.options.explain = true;
-      return executeOperation(this.topology, this.operation as any, callback);
-    }
+    // TODO: uncomment/fix this when cursor explain is re-implemented
+    // if (this.operation && this.operation.cmd == null) {
+    //   this.operation.options.explain = true;
+    //   return executeOperation(this.topology, this.operation as any, callback);
+    // }
 
     this.cmd.explain = true;
 

src/explain.ts

@@ -0,0 +1,78 @@
+import type { Document } from '.';
+import type { ExplainOptions } from './operations/explainable_command';
+import type { Server } from './sdam/server';
+import { maxWireVersion } from './utils';
+
+/** @public */
+export enum Verbosity {
+  queryPlanner = 'queryPlanner',
+  queryPlannerExtended = 'queryPlannerExtended',
+  executionStats = 'executionStats',
+  allPlansExecution = 'allPlansExecution'
+}
+
+/**
+ * For backwards compatibility, true is interpreted as
+ * "allPlansExecution" and false as "queryPlanner".
+ * @public
+ */
+export type VerbosityLike = Verbosity | boolean;
+
+// Minimum server versions which support explain with specific operations
+const SUPPORTS_EXPLAIN_WITH_REMOVE = 3;
+const SUPPORTS_EXPLAIN_WITH_UPDATE = 3;
+const SUPPORTS_EXPLAIN_WITH_DISTINCT = 3.2;
+const SUPPORTS_EXPLAIN_WITH_FIND_AND_MODIFY = 3.2;
+const SUPPORTS_EXPLAIN_WITH_MAP_REDUCE = 4.4;
+
+/** @internal */
+export class Explain {
+  verbosity: Verbosity;
+
+  constructor(verbosity: VerbosityLike) {
+    if (typeof verbosity === 'boolean') {
+      this.verbosity = verbosity ? Verbosity.allPlansExecution : Verbosity.queryPlanner;
+    } else {
+      this.verbosity = Verbosity[verbosity];
+    }
+  }
+
+  static fromOptions(options?: ExplainOptions): Explain | undefined {
+    if (options == null || options.explain === undefined) {
+      return;
+    }
+    return new Explain(options.explain);
+  }
+
+  static valid(options?: ExplainOptions): boolean {
+    if (options == null || options.explain === undefined) {
+      return true;
+    }
+    const explain = options.explain;
+    return typeof explain === 'boolean' || explain in Verbosity;
+  }
+
+  /** Checks that the server supports explain on the given operation.*/
+  static explainSupported(server: Server, op: string): boolean {
+    const wireVersion = maxWireVersion(server);
+    return (
+      (op === 'remove' && wireVersion >= SUPPORTS_EXPLAIN_WITH_REMOVE) ||
+      (op === 'update' && wireVersion >= SUPPORTS_EXPLAIN_WITH_UPDATE) ||
+      (op === 'distinct' && wireVersion >= SUPPORTS_EXPLAIN_WITH_DISTINCT) ||
+      (op === 'findAndModify' && wireVersion >= SUPPORTS_EXPLAIN_WITH_FIND_AND_MODIFY) ||
+      (op === 'mapReduce' && wireVersion >= SUPPORTS_EXPLAIN_WITH_MAP_REDUCE)
+    );
+  }
+
+  /** Checks that the server supports explain on the given command.*/
+  static explainSupportedOnCmd(server: Server, cmd: Document): boolean {
+    const wireVersion = maxWireVersion(server);
+    return (
+      (cmd.remove && wireVersion >= SUPPORTS_EXPLAIN_WITH_REMOVE) ||
+      (cmd.update && wireVersion >= SUPPORTS_EXPLAIN_WITH_UPDATE) ||
+      (cmd.distinct && wireVersion >= SUPPORTS_EXPLAIN_WITH_DISTINCT) ||
+      (cmd.findAndModify && wireVersion >= SUPPORTS_EXPLAIN_WITH_FIND_AND_MODIFY) ||
+      (cmd.mapReduce && wireVersion >= SUPPORTS_EXPLAIN_WITH_MAP_REDUCE)
+    );
+  }
+}

src/operations/command.ts

@@ -1,7 +1,7 @@
 import { Aspect, OperationBase, OperationOptions } from './operation';
 import { ReadConcern } from '../read_concern';
 import { WriteConcern, WriteConcernOptions } from '../write_concern';
-import { maxWireVersion, MongoDBNamespace, Callback } from '../utils';
+import { maxWireVersion, MongoDBNamespace, Callback, decorateWithExplain } from '../utils';
 import { ReadPreference, ReadPreferenceLike } from '../read_preference';
 import { commandSupportsReadConcern } from '../sessions';
 import { MongoError } from '../error';
@@ -54,7 +54,6 @@ export abstract class CommandOperation<
   readPreference: ReadPreference;
   readConcern?: ReadConcern;
   writeConcern?: WriteConcern;
-  explain: boolean;
   fullResponse?: boolean;
   logger?: Logger;
 
@@ -79,7 +78,6 @@ export abstract class CommandOperation<
       : ReadPreference.resolve(propertyProvider, this.options);
     this.readConcern = resolveReadConcern(propertyProvider, this.options);
     this.writeConcern = resolveWriteConcern(propertyProvider, this.options);
-    this.explain = false;
     this.fullResponse =
       options && typeof options.fullResponse === 'boolean' ? options.fullResponse : false;
 
@@ -141,6 +139,12 @@ export abstract class CommandOperation<
       this.logger.debug(`executing command ${JSON.stringify(cmd)} against ${this.ns}`);
     }
 
+    // If a command is to be explained, we need to reformat the command after
+    // the other command properties are specified.
+    if (cmd.explain) {
+      cmd = decorateWithExplain(cmd, cmd.explain);
+    }
+
     server.command(
       this.ns.toString(),
       cmd,

src/operations/delete.ts

@@ -1,16 +1,17 @@
 import { defineAspects, Aspect, OperationBase, Hint } from './operation';
 import { removeDocuments } from './common_functions';
-import { CommandOperation, CommandOperationOptions } from './command';
 import { isObject } from 'util';
 import type { Callback, MongoDBNamespace } from '../utils';
 import type { Document } from '../bson';
 import type { Server } from '../sdam/server';
 import type { Collection } from '../collection';
 import type { WriteCommandOptions } from '../cmap/wire_protocol/write_command';
 import type { Connection } from '../cmap/connection';
+import { ExplainableCommand, ExplainOptions } from '../operations/explainable_command';
+import type { CommandOperationOptions } from './command';
 
 /** @public */
-export interface DeleteOptions extends CommandOperationOptions {
+export interface DeleteOptions extends CommandOperationOptions, ExplainOptions {
   single?: boolean;
   hint?: Hint;
 }
@@ -51,7 +52,7 @@ export class DeleteOperation extends OperationBase<DeleteOptions, Document> {
   }
 }
 
-export class DeleteOneOperation extends CommandOperation<DeleteOptions, DeleteResult> {
+export class DeleteOneOperation extends ExplainableCommand<DeleteOptions, DeleteResult> {
   collection: Collection;
   filter: Document;
 
@@ -81,7 +82,7 @@ export class DeleteOneOperation extends CommandOperation<DeleteOptions, DeleteRe
   }
 }
 
-export class DeleteManyOperation extends CommandOperation<DeleteOptions, DeleteResult> {
+export class DeleteManyOperation extends ExplainableCommand<DeleteOptions, DeleteResult> {
   collection: Collection;
   filter: Document;
 

src/operations/distinct.ts

@@ -1,18 +1,19 @@
 import { Aspect, defineAspects } from './operation';
-import { CommandOperation, CommandOperationOptions } from './command';
 import { decorateWithCollation, decorateWithReadConcern, Callback } from '../utils';
 import type { Document } from '../bson';
 import type { Server } from '../sdam/server';
 import type { Collection } from '../collection';
+import { ExplainableCommand, ExplainOptions } from '../operations/explainable_command';
+import type { CommandOperationOptions } from './command';
 
 /** @public */
-export type DistinctOptions = CommandOperationOptions;
+export interface DistinctOptions extends CommandOperationOptions, ExplainOptions {}
 
 /**
  * Return a list of distinct values for the given key across a collection.
  * @internal
  */
-export class DistinctOperation extends CommandOperation<DistinctOptions, Document[]> {
+export class DistinctOperation extends ExplainableCommand<DistinctOptions, Document[]> {
   collection: Collection;
   /** Field of the document to find distinct values for. */
   key: string;
@@ -69,7 +70,7 @@ export class DistinctOperation extends CommandOperation<DistinctOptions, Documen
         return;
       }
 
-      callback(undefined, this.options.fullResponse ? result : result.values);
+      callback(undefined, this.options.fullResponse || this.explain ? result : result.values);
     });
   }
 }

src/operations/explainable_command.ts

@@ -0,0 +1,44 @@
+import { CommandOperation, OperationParent, CommandOperationOptions } from './command';
+import { Explain, Verbosity, VerbosityLike } from '../explain';
+import { Callback, Document, MongoError, Server } from '..';
+
+/** @public */
+export interface ExplainOptions {
+  explain?: VerbosityLike;
+}
+
+/** @internal */
+export abstract class ExplainableCommand<
+  T extends ExplainOptions & CommandOperationOptions,
+  TResult = Document
+> extends CommandOperation<T, TResult> {
+  explain?: Explain;
+
+  constructor(parent?: OperationParent, options?: T) {
+    super(parent, options);
+
+    if (!Explain.valid(options)) {
+      throw new MongoError(`explain must be one of ${Object.keys(Verbosity)} or a boolean`);
+    }
+
+    this.explain = Explain.fromOptions(options);
+  }
+
+  get canRetryWrite(): boolean {
+    return this.explain === undefined;
+  }
+
+  executeCommand(server: Server, cmd: Document, callback: Callback): void {
+    if (this.explain) {
+      if (!Explain.explainSupportedOnCmd(server, cmd)) {
+        callback(new MongoError(`server ${server.name} does not support explain on this command`));
+        return;
+      }
+
+      // For now, tag the command with the explain; after cmd is finalized in the super class,
+      // it will be refactored into the required shape using the explain.
+      cmd.explain = this.explain;
+    }
+    super.executeCommand(server, cmd, callback);
+  }
+}

src/operations/find_and_modify.ts

@@ -8,15 +8,16 @@ import {
   Callback
 } from '../utils';
 import { MongoError } from '../error';
-import { CommandOperation, CommandOperationOptions } from './command';
 import { defineAspects, Aspect } from './operation';
 import type { Document } from '../bson';
 import type { Server } from '../sdam/server';
 import type { Collection } from '../collection';
 import { Sort, formatSort } from '../sort';
+import { ExplainableCommand, ExplainOptions } from '../operations/explainable_command';
+import type { CommandOperationOptions } from './command';
 
 /** @public */
-export interface FindAndModifyOptions extends CommandOperationOptions {
+export interface FindAndModifyOptions extends CommandOperationOptions, ExplainOptions {
   /** When false, returns the updated document rather than the original. The default is true. */
   returnOriginal?: boolean;
   /** Upsert the document if it does not exist. */
@@ -41,7 +42,7 @@ export interface FindAndModifyOptions extends CommandOperationOptions {
 }
 
 /** @internal */
-export class FindAndModifyOperation extends CommandOperation<FindAndModifyOptions, Document> {
+export class FindAndModifyOperation extends ExplainableCommand<FindAndModifyOptions, Document> {
   collection: Collection;
   query: Document;
   sort?: Sort;

src/operations/find_one.ts

@@ -1,24 +1,21 @@
-import { OperationBase } from './operation';
 import type { Callback } from '../utils';
-import { Document, resolveBSONOptions } from '../bson';
+import type { Document } from '../bson';
 import type { Collection } from '../collection';
 import type { FindOptions } from './find';
 import { MongoError } from '../error';
 import type { Server } from '../sdam/server';
+import { CommandOperation } from './command';
 
 /** @internal */
-export class FindOneOperation extends OperationBase<FindOptions, Document> {
+export class FindOneOperation extends CommandOperation<FindOptions, Document> {
   collection: Collection;
   query: Document;
 
   constructor(collection: Collection, query: Document, options: FindOptions) {
-    super(options);
+    super(collection, options);
 
     this.collection = collection;
     this.query = query;
-
-    // Assign BSON serialize options to OperationBase, preferring options over collection options
-    this.bsonOptions = resolveBSONOptions(options, collection);
   }
 
   execute(server: Server, callback: Callback<Document>): void {