feat(NODE-6419): deprecate explain options API for find and aggregate (…

…#4271)

src/operations/aggregate.ts

@@ -1,6 +1,7 @@
 import type { Document } from '../bson';
 import { CursorResponse, ExplainedCursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError } from '../error';
+import { type ExplainOptions } from '../explain';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
 import { maxWireVersion, type MongoDBNamespace } from '../utils';
@@ -14,7 +15,7 @@ export const DB_AGGREGATE_COLLECTION = 1 as const;
 const MIN_WIRE_VERSION_$OUT_READ_CONCERN_SUPPORT = 8;
 
 /** @public */
-export interface AggregateOptions extends CommandOperationOptions {
+export interface AggregateOptions extends Omit<CommandOperationOptions, 'explain'> {
   /** allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 \>). */
   allowDiskUse?: boolean;
   /** The number of documents to return per batch. See [aggregation documentation](https://www.mongodb.com/docs/manual/reference/command/aggregate). */
@@ -35,6 +36,13 @@ export interface AggregateOptions extends CommandOperationOptions {
   let?: Document;
 
   out?: string;
+
+  /**
+   * Specifies the verbosity mode for the explain output.
+   * @deprecated This API is deprecated in favor of `collection.aggregate().explain()`
+   * or `db.aggregate().explain()`.
+   */
+  explain?: ExplainOptions['explain'];
 }
 
 /** @internal */

src/operations/find.ts

@@ -1,6 +1,7 @@
 import type { Document } from '../bson';
 import { CursorResponse, ExplainedCursorResponse } from '../cmap/wire_protocol/responses';
 import { MongoInvalidArgumentError } from '../error';
+import { type ExplainOptions } from '../explain';
 import { ReadConcern } from '../read_concern';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
@@ -15,7 +16,7 @@ import { Aspect, defineAspects, type Hint } from './operation';
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface FindOptions<TSchema extends Document = Document>
-  extends Omit<CommandOperationOptions, 'writeConcern'> {
+  extends Omit<CommandOperationOptions, 'writeConcern' | 'explain'> {
   /** Sets the limit of documents returned in the query. */
   limit?: number;
   /** Set to sort the documents coming back from the query. Array of indexes, `[['a', 1]]` etc. */
@@ -63,6 +64,12 @@ export interface FindOptions<TSchema extends Document = Document>
    * @deprecated Starting from MongoDB 4.4 this flag is not needed and will be ignored.
    */
   oplogReplay?: boolean;
+
+  /**
+   * Specifies the verbosity mode for the explain output.
+   * @deprecated This API is deprecated in favor of `collection.find().explain()`.
+   */
+  explain?: ExplainOptions['explain'];
 }
 
 /** @internal */