feat: add explain support for non-cursor commands

src/cmap/wire_protocol/write_command.ts

@@ -1,9 +1,10 @@
 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, ExplainOptions } from '../../explain';
 
 /** @public */
 export interface CollationOptions {
@@ -18,7 +19,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 +44,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 +65,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,76 @@
+import type { Document } from '.';
+import { MongoError } from './error';
+import type { Server } from './sdam/server';
+import { maxWireVersion } from './utils';
+
+/** @public */
+export const ExplainVerbosity = {
+  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 ExplainVerbosityLike = keyof typeof ExplainVerbosity | boolean;
+
+/** @public */
+export interface ExplainOptions {
+  /** Specifies the verbosity mode for the explain output. */
+  explain?: ExplainVerbosityLike;
+}
+
+// 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 ExplainVerbosity;
+
+  constructor(verbosity: ExplainVerbosityLike) {
+    if (typeof verbosity === 'boolean') {
+      this.verbosity = verbosity
+        ? ExplainVerbosity.allPlansExecution
+        : ExplainVerbosity.queryPlanner;
+    } else {
+      this.verbosity = ExplainVerbosity[verbosity];
+    }
+  }
+
+  static fromOptions(options?: ExplainOptions): Explain | undefined {
+    if (options?.explain === undefined) return;
+
+    const explain = options.explain;
+    if (typeof explain === 'boolean' || explain in ExplainVerbosity) {
+      return new Explain(explain);
+    }
+
+    throw new MongoError(`explain must be one of ${Object.keys(ExplainVerbosity)} or a boolean`);
+  }
+
+  /** 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/index.ts

@@ -163,6 +163,11 @@ export type {
 export type { DbPrivate, DbOptions } from './db';
 export type { AutoEncryptionOptions, AutoEncryptionLoggerLevels, AutoEncrypter } from './deps';
 export type { AnyError, ErrorDescription } from './error';
+export type {
+  ExplainOptions,
+  ExplainVerbosity as Verbosity,
+  ExplainVerbosityLike as VerbosityLike
+} from './explain';
 export type {
   GridFSBucketReadStream,
   GridFSBucketReadStreamOptions,

src/operations/aggregate.ts

@@ -22,8 +22,6 @@ export interface AggregateOptions extends CommandOperationOptions {
   bypassDocumentValidation?: boolean;
   /** Return the query as cursor, on 2.6 \> it returns as a real cursor on pre 2.6 it returns as an emulated cursor. */
   cursor?: Document;
-  /** Explain returns the aggregation execution plan (requires mongodb 2.6 \>) */
-  explain?: boolean;
   /** specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point. */
   maxTimeMS?: number;
   /** The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query. */

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';
@@ -10,11 +10,15 @@ import type { Server } from '../sdam/server';
 import { BSONSerializeOptions, Document, resolveBSONOptions } from '../bson';
 import type { CollationOptions } from '../cmap/wire_protocol/write_command';
 import type { ReadConcernLike } from './../read_concern';
+import { Explain, ExplainOptions } from '../explain';
 
 const SUPPORTS_WRITE_CONCERN_AND_COLLATION = 5;
 
 /** @public */
-export interface CommandOperationOptions extends OperationOptions, WriteConcernOptions {
+export interface CommandOperationOptions
+  extends OperationOptions,
+    WriteConcernOptions,
+    ExplainOptions {
   /** Return the full server response for the command */
   fullResponse?: boolean;
   /** Specify a read concern and level for the collection. (only MongoDB 3.2 or higher supported) */
@@ -54,7 +58,7 @@ export abstract class CommandOperation<
   readPreference: ReadPreference;
   readConcern?: ReadConcern;
   writeConcern?: WriteConcern;
-  explain: boolean;
+  explain?: Explain;
   fullResponse?: boolean;
   logger?: Logger;
 
@@ -80,7 +84,6 @@ export abstract class CommandOperation<
     this.writeConcern = WriteConcern.fromOptions(options);
     this.bsonOptions = resolveBSONOptions(options);
 
-    this.explain = false;
     this.fullResponse =
       options && typeof options.fullResponse === 'boolean' ? options.fullResponse : false;
 
@@ -92,6 +95,19 @@ export abstract class CommandOperation<
     if (parent && parent.logger) {
       this.logger = parent.logger;
     }
+
+    if (this.hasAspect(Aspect.EXPLAINABLE)) {
+      this.explain = Explain.fromOptions(options);
+    } else if (options?.explain !== undefined) {
+      throw new MongoError(`explain is not supported on this command`);
+    }
+  }
+
+  get canRetryWrite(): boolean {
+    if (this.hasAspect(Aspect.EXPLAINABLE)) {
+      return this.explain === undefined;
+    }
+    return true;
   }
 
   abstract execute(server: Server, callback: Callback<TResult>): void;
@@ -139,6 +155,15 @@ export abstract class CommandOperation<
       this.logger.debug(`executing command ${JSON.stringify(cmd)} against ${this.ns}`);
     }
 
+    if (this.hasAspect(Aspect.EXPLAINABLE) && this.explain) {
+      if (!Explain.explainSupported(server, cmd)) {
+        callback(new MongoError(`server ${server.name} does not support explain on this command`));
+        return;
+      }
+
+      cmd = decorateWithExplain(cmd, this.explain);
+    }
+
     server.command(
       this.ns.toString(),
       cmd,

src/operations/delete.ts

@@ -120,5 +120,5 @@ export class DeleteManyOperation extends CommandOperation<DeleteOptions, DeleteR
 }
 
 defineAspects(DeleteOperation, [Aspect.RETRYABLE, Aspect.WRITE_OPERATION]);
-defineAspects(DeleteOneOperation, [Aspect.RETRYABLE, Aspect.WRITE_OPERATION]);
-defineAspects(DeleteManyOperation, [Aspect.WRITE_OPERATION]);
+defineAspects(DeleteOneOperation, [Aspect.RETRYABLE, Aspect.WRITE_OPERATION, Aspect.EXPLAINABLE]);
+defineAspects(DeleteManyOperation, [Aspect.WRITE_OPERATION, Aspect.EXPLAINABLE]);

src/operations/distinct.ts

@@ -69,9 +69,9 @@ 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);
     });
   }
 }
 
-defineAspects(DistinctOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE]);
+defineAspects(DistinctOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE, Aspect.EXPLAINABLE]);

src/operations/find.ts

@@ -21,8 +21,6 @@ export interface FindOptions extends QueryOptions, CommandOperationOptions {
   skip?: number;
   /** Tell the query to use specific indexes in the query. Object of indexes to use, `{'_id':1}` */
   hint?: Hint;
-  /** Explain the query instead of returning the data. */
-  explain?: boolean;
   /** Specify if the cursor can timeout. */
   timeout?: boolean;
   /** Specify if the cursor is tailable. */

src/operations/find_and_modify.ts

@@ -231,4 +231,8 @@ export class FindOneAndUpdateOperation extends FindAndModifyOperation {
   }
 }
 
-defineAspects(FindAndModifyOperation, [Aspect.WRITE_OPERATION, Aspect.RETRYABLE]);
+defineAspects(FindAndModifyOperation, [
+  Aspect.WRITE_OPERATION,
+  Aspect.RETRYABLE,
+  Aspect.EXPLAINABLE
+]);

src/operations/map_reduce.ts

@@ -14,8 +14,10 @@ import type { Collection } from '../collection';
 import type { Sort } from '../sort';
 import { MongoError } from '../error';
 import type { ObjectId } from '../bson';
+import { Aspect, defineAspects } from './operation';
 
 const exclusionList = [
+  'explain',
   'readPreference',
   'readConcern',
   'session',
@@ -164,6 +166,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;
@@ -227,3 +232,5 @@ function processScope(scope: Document | ObjectId) {
 
   return newScope;
 }
+
+defineAspects(MapReduceOperation, [Aspect.EXPLAINABLE]);

src/operations/operation.ts

@@ -7,7 +7,8 @@ import type { Server } from '../sdam/server';
 export const Aspect = {
   READ_OPERATION: Symbol('READ_OPERATION'),
   WRITE_OPERATION: Symbol('WRITE_OPERATION'),
-  RETRYABLE: Symbol('RETRYABLE')
+  RETRYABLE: Symbol('RETRYABLE'),
+  EXPLAINABLE: Symbol('EXPLAINABLE')
 } as const;
 
 /** @public */
@@ -21,8 +22,6 @@ export interface OperationConstructor extends Function {
 export interface OperationOptions extends BSONSerializeOptions {
   /** Specify ClientSession for this command */
   session?: ClientSession;
-
-  explain?: boolean;
   willRetryWrites?: boolean;
 }
 

src/operations/update.ts

@@ -94,6 +94,9 @@ export class UpdateOneOperation extends CommandOperation<UpdateOptions, UpdateRe
     updateDocuments(server, coll, filter, update, options, (err, r) => {
       if (err || !r) return callback(err);
 
+      // If an explain option was executed, don't process the server results
+      if (this.explain) return callback(undefined, r);
+
       const result: UpdateResult = {
         modifiedCount: r.nModified != null ? r.nModified : r.n,
         upsertedId:
@@ -136,6 +139,9 @@ export class UpdateManyOperation extends CommandOperation<UpdateOptions, UpdateR
     updateDocuments(server, coll, filter, update, options, (err, r) => {
       if (err || !r) return callback(err);
 
+      // If an explain option was executed, don't process the server results
+      if (this.explain) return callback(undefined, r);
+
       const result: UpdateResult = {
         modifiedCount: r.nModified != null ? r.nModified : r.n,
         upsertedId:
@@ -153,5 +159,5 @@ export class UpdateManyOperation extends CommandOperation<UpdateOptions, UpdateR
 }
 
 defineAspects(UpdateOperation, [Aspect.RETRYABLE, Aspect.WRITE_OPERATION]);
-defineAspects(UpdateOneOperation, [Aspect.RETRYABLE, Aspect.WRITE_OPERATION]);
-defineAspects(UpdateManyOperation, [Aspect.WRITE_OPERATION]);
+defineAspects(UpdateOneOperation, [Aspect.RETRYABLE, Aspect.WRITE_OPERATION, Aspect.EXPLAINABLE]);
+defineAspects(UpdateManyOperation, [Aspect.WRITE_OPERATION, Aspect.EXPLAINABLE]);

src/sdam/server.ts

@@ -45,6 +45,7 @@ import type { WriteCommandOptions } from '../cmap/wire_protocol/write_command';
 import type { Document, Long } from '../bson';
 import type { AutoEncrypter } from '../deps';
 import type { FindOptions } from '../operations/find';
+import { Explain } from '../explain';
 
 // Used for filtering out fields for logging
 const DEBUG_FIELDS = [
@@ -457,6 +458,11 @@ function executeWriteOperation(
     }
   }
 
+  if (options.explain !== undefined && !Explain.explainSupported(server, op)) {
+    callback(new MongoError(`server ${server.name} does not support explain on ${op}`));
+    return;
+  }
+
   server.s.pool.withConnection((err, conn, cb) => {
     if (err || !conn) {
       markServerUnknown(server, err);