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,12 @@ 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 NODE-2853: This had to be removed during NODE-2852; fix while re-implementing
+    // cursor explain
+    // 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,71 @@
+import type { Document } from '.';
+import type { ExplainOptions } from './operations/explainable_command';
+import type { Server } from './sdam/server';
+import { maxWireVersion } from './utils';
+
+export const Verbosity = {
+  queryPlanner: 'queryPlanner',
+  queryPlannerExtended: 'queryPlannerExtended',
+  executionStats: 'executionStats',
+  allPlansExecution: 'allPlansExecution'
+} as const;
+
+/**
+ * For backwards compatibility, true is interpreted as
+ * "allPlansExecution" and false as "queryPlanner".
+ * @public
+ */
+export type VerbosityLike = keyof typeof 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 = 4;
+const SUPPORTS_EXPLAIN_WITH_FIND_AND_MODIFY = 4;
+const SUPPORTS_EXPLAIN_WITH_MAP_REDUCE = 9;
+
+/** @internal */
+export class Explain {
+  verbosity: keyof typeof 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?.explain === undefined) {
+      return;
+    }
+    return new Explain(options.explain);
+  }
+
+  static valid(options?: ExplainOptions): boolean {
+    if (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 or command.*/
+  static explainSupported(server: Server, op: string | Document): boolean {
+    const wireVersion = maxWireVersion(server);
+    if (op === 'remove' || (typeof op === 'object' && op.remove)) {
+      return wireVersion >= SUPPORTS_EXPLAIN_WITH_REMOVE;
+    } else if (op === 'update' || (typeof op === 'object' && op.update)) {
+      return wireVersion >= SUPPORTS_EXPLAIN_WITH_UPDATE;
+    } else if (op === 'distinct' || (typeof op === 'object' && op.distinct)) {
+      return wireVersion >= SUPPORTS_EXPLAIN_WITH_DISTINCT;
+    } else if (op === 'findAndModify' || (typeof op === 'object' && op.findAndModify)) {
+      return wireVersion >= SUPPORTS_EXPLAIN_WITH_FIND_AND_MODIFY;
+    } else if (op === 'mapReduce' || (typeof op === 'object' && op.mapReduce)) {
+      return wireVersion >= SUPPORTS_EXPLAIN_WITH_MAP_REDUCE;
+    }
+
+    return false;
+  }
+}

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,9 +139,11 @@ 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.
     server.command(
       this.ns.toString(),
-      cmd,
+      cmd.explain ? decorateWithExplain(cmd, cmd.explain) : cmd,
       { fullResult: !!this.fullResponse, ...this.options },
       callback
     );

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.explainSupported(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/map_reduce.ts

@@ -8,14 +8,16 @@ import {
   Callback
 } from '../utils';
 import { ReadPreference, ReadPreferenceMode } from '../read_preference';
-import { CommandOperation, CommandOperationOptions } from './command';
 import type { Server } from '../sdam/server';
 import type { Collection } from '../collection';
 import type { Sort } from '../sort';
 import { MongoError } from '../error';
 import type { ObjectId } from '../bson';
+import { ExplainableCommand, ExplainOptions } from '../operations/explainable_command';
+import type { CommandOperationOptions } from './command';
 
 const exclusionList = [
+  'explain',
   'readPreference',
   'session',
   'bypassDocumentValidation',
@@ -34,7 +36,7 @@ export type ReduceFunction = (key: string, values: Document[]) => Document;
 export type FinalizeFunction = (key: string, reducedValue: Document) => Document;
 
 /** @public */
-export interface MapReduceOptions extends CommandOperationOptions {
+export interface MapReduceOptions extends CommandOperationOptions, ExplainOptions {
   /** Sets the output target for the map reduce job. */
   out?: 'inline' | { inline: 1 } | { replace: string } | { merge: string } | { reduce: string };
   /** Query filter object. */
@@ -67,7 +69,10 @@ interface MapReduceStats {
  * Run Map Reduce across a collection. Be aware that the inline option for out will return an array of results not a collection.
  * @internal
  */
-export class MapReduceOperation extends CommandOperation<MapReduceOptions, Document | Document[]> {
+export class MapReduceOperation extends ExplainableCommand<
+  MapReduceOptions,
+  Document | Document[]
+> {
   collection: Collection;
   /** The mapping function. */
   map: MapFunction | string;
@@ -160,6 +165,9 @@ export class MapReduceOperation extends CommandOperation<MapReduceOptions, Docum
         return callback(new MongoError(result));
       }
 
+      // If an explain option was executed, don't process the server results
+      if (this.explain) return callback(undefined, result);
+
       // Create statistics value
       const stats: MapReduceStats = {};
       if (result.timeMillis) stats['processtime'] = result.timeMillis;

src/operations/operation.ts

@@ -22,8 +22,6 @@ export interface OperationConstructor extends Function {
 export interface OperationOptions extends BSONSerializeOptions {
   /** Specify ClientSession for this command */
   session?: ClientSession;
-
-  explain?: boolean;
   willRetryWrites?: boolean;
 }