feat: use placeholder mql types MONGOSH-2333

packages/shell-api/src/bulk.ts

@@ -21,6 +21,7 @@ import { asPrintable } from './enums';
 import { assertArgsDefinedType, shallowClone } from './helpers';
 import { BulkWriteResult } from './result';
 import type { CollectionWithSchema } from './collection';
+import type { MQLDocument, MQLQuery } from './mql-types';
 
 @shellApiClassDefault
 export class BulkFindOp extends ShellApiWithMongoClass {
@@ -202,14 +203,14 @@ export default class Bulk extends ShellApiWithMongoClass {
 
   @returnType('BulkFindOp')
   @apiVersions([1])
-  find(query: Document): BulkFindOp {
+  find(query: MQLQuery): BulkFindOp {
     assertArgsDefinedType([query], [true], 'Bulk.find');
     return new BulkFindOp(this._serviceProviderBulkOp.find(query), this);
   }
 
   @returnType('Bulk')
   @apiVersions([1])
-  insert(document: Document): Bulk {
+  insert(document: MQLDocument): Bulk {
     this._batchCounts.nInsertOps++;
     assertArgsDefinedType([document], [true], 'Bulk.insert');
     this._serviceProviderBulkOp.insert(document);

packages/shell-api/src/collection.ts

@@ -96,6 +96,7 @@ import { HIDDEN_COMMANDS } from '@mongosh/history';
 import PlanCache from './plan-cache';
 import ChangeStreamCursor from './change-stream-cursor';
 import { ShellApiErrors } from './error-codes';
+import type { MQLDocument, MQLQuery, MQLPipeline } from './mql-types';
 
 export type CollectionWithSchema<
   M extends GenericServerSideSchema = GenericServerSideSchema,
@@ -188,20 +189,20 @@ export class Collection<
    * @returns {Promise} The promise of aggregation results.
    */
   async aggregate(
-    pipeline: Document[],
+    pipeline: MQLPipeline,
     options: AggregateOptions & { explain: ExplainVerbosityLike }
   ): Promise<Document>;
   async aggregate(
-    pipeline: Document[],
+    pipeline: MQLPipeline,
     options?: AggregateOptions
   ): Promise<AggregationCursor>;
-  async aggregate(...stages: Document[]): Promise<AggregationCursor>;
+  async aggregate(...stages: MQLPipeline): Promise<AggregationCursor>;
   @returnsPromise
   @returnType('AggregationCursor')
   @apiVersions([1])
   async aggregate(...args: unknown[]): Promise<AggregationCursor | Document> {
     let options: AggregateOptions;
-    let pipeline: Document[];
+    let pipeline: MQLPipeline;
     if (args.length === 0 || Array.isArray(args[0])) {
       options = args[1] || {};
       pipeline = (args[0] as Document[]) || [];
@@ -320,7 +321,7 @@ export class Collection<
   @serverVersions(['4.0.3', ServerVersions.latest])
   @apiVersions([1])
   async countDocuments(
-    query?: Document,
+    query?: MQLQuery,
     options: CountDocumentsOptions = {}
   ): Promise<number> {
     this._emitCollectionApiCall('countDocuments', { query, options });
@@ -413,17 +414,17 @@ export class Collection<
    * @returns {Array} The promise of the result.
    */
   async distinct(field: string): Promise<Document>;
-  async distinct(field: string, query: Document): Promise<Document>;
+  async distinct(field: string, query: MQLQuery): Promise<Document>;
   async distinct(
     field: string,
-    query: Document,
+    query: MQLQuery,
     options: DistinctOptions
   ): Promise<Document>;
   @returnsPromise
   @apiVersions([])
   async distinct(
     field: string,
-    query?: Document,
+    query?: MQLQuery,
     options: DistinctOptions = {}
   ): Promise<Document> {
     this._emitCollectionApiCall('distinct', { field, query, options });
@@ -476,7 +477,7 @@ export class Collection<
   @apiVersions([1])
   @returnsPromise
   async find(
-    query?: Document,
+    query?: MQLQuery,
     projection?: Document,
     options: FindOptions = {}
   ): Promise<Cursor> {
@@ -560,10 +561,10 @@ export class Collection<
   @returnType('Document')
   @apiVersions([1])
   async findOne(
-    query: Document = {},
+    query: MQLQuery = {},
     projection?: Document,
     options: FindOptions = {}
-  ): Promise<C['schema'] | null> {
+  ): Promise<MQLDocument | null> {
     if (projection) {
       options.projection = projection;
     }
@@ -757,7 +758,7 @@ export class Collection<
   @serverVersions([ServerVersions.earliest, '3.6.0'])
   @apiVersions([1])
   async insert(
-    docs: Document | Document[],
+    docs: MQLDocument | MQLDocument[],
     options: BulkWriteOptions = {}
   ): Promise<InsertManyResult> {
     await this._instanceState.printDeprecationWarning(
@@ -801,7 +802,7 @@ export class Collection<
   @serverVersions(['3.2.0', ServerVersions.latest])
   @apiVersions([1])
   async insertMany(
-    docs: Document[],
+    docs: MQLDocument[],
     options: BulkWriteOptions = {}
   ): Promise<InsertManyResult> {
     assertArgsDefinedType([docs], [true], 'Collection.insertMany');
@@ -837,7 +838,7 @@ export class Collection<
   @serverVersions(['3.2.0', ServerVersions.latest])
   @apiVersions([1])
   async insertOne(
-    doc: Document,
+    doc: MQLDocument,
     options: InsertOneOptions = {}
   ): Promise<InsertOneResult> {
     assertArgsDefinedType([doc], [true], 'Collection.insertOne');
@@ -893,7 +894,7 @@ export class Collection<
   @serverVersions([ServerVersions.earliest, '3.2.0'])
   @apiVersions([1])
   async remove(
-    query: Document,
+    query: MQLQuery,
     options: boolean | RemoveShellOptions = {}
   ): Promise<DeleteResult | Document> {
     await this._instanceState.printDeprecationWarning(
@@ -2332,7 +2333,7 @@ export class Collection<
   @apiVersions([1])
   @returnsPromise
   async watch(
-    pipeline: Document[] | ChangeStreamOptions = [],
+    pipeline: MQLPipeline | ChangeStreamOptions = [],
     options: ChangeStreamOptions = {}
   ): Promise<ChangeStreamCursor> {
     if (!Array.isArray(pipeline)) {

packages/shell-api/src/database.ts

@@ -61,6 +61,7 @@ import type {
   ExplainVerbosityLike,
   AggregateOptions,
 } from '@mongosh/service-provider-core';
+import type { MQLPipeline } from './mql-types';
 
 export type CollectionNamesWithTypes = {
   name: string;
@@ -443,26 +444,26 @@ export class Database<
    * @returns {Promise} The promise of aggregation results.
    */
   async aggregate(
-    pipeline: Document[],
+    pipeline: MQLPipeline,
     options: AggregateOptions & { explain: ExplainVerbosityLike }
   ): Promise<Document>;
   async aggregate(
-    pipeline: Document[],
+    pipeline: MQLPipeline,
     options?: AggregateOptions
   ): Promise<AggregationCursor>;
-  async aggregate(...stages: Document[]): Promise<AggregationCursor>;
+  async aggregate(...stages: MQLPipeline): Promise<AggregationCursor>;
   @returnsPromise
   @returnType('AggregationCursor')
   @apiVersions([1])
   async aggregate(...args: unknown[]): Promise<AggregationCursor | Document> {
     let options: AggregateOptions;
-    let pipeline: Document[];
+    let pipeline: MQLPipeline;
     if (args.length === 0 || Array.isArray(args[0])) {
       options = args[1] || {};
-      pipeline = (args[0] as Document[]) || [];
+      pipeline = (args[0] as MQLPipeline) || [];
     } else {
       options = {};
-      pipeline = (args as Document[]) || [];
+      pipeline = (args as MQLPipeline) || [];
     }
 
     if ('background' in options) {
@@ -855,7 +856,7 @@ export class Database<
   async createView(
     name: string,
     source: string,
-    pipeline: Document[],
+    pipeline: MQLPipeline,
     options: CreateCollectionOptions = {}
   ): Promise<{ ok: number }> {
     assertArgsDefinedType(
@@ -1085,7 +1086,7 @@ export class Database<
         ? { $all: opts, $ownOps: false }
         : { $all: !!opts.$all, $ownOps: !!opts.$ownOps };
 
-    const pipeline: Document[] = [
+    const pipeline: MQLPipeline = [
       {
         $currentOp: {
           allUsers: !legacyCurrentOpOptions.$ownOps,
@@ -1739,7 +1740,7 @@ export class Database<
   @apiVersions([1])
   @returnsPromise
   async watch(
-    pipeline: Document[] | ChangeStreamOptions = [],
+    pipeline: MQLPipeline | ChangeStreamOptions = [],
     options: ChangeStreamOptions = {}
   ): Promise<ChangeStreamCursor> {
     if (!Array.isArray(pipeline)) {

packages/shell-api/src/explainable.ts

@@ -33,6 +33,7 @@ import type {
   FindOneAndUpdateOptions,
   FindOptions,
 } from '@mongosh/service-provider-core';
+import type { MQLDocument, MQLPipeline, MQLQuery } from './mql-types';
 
 @shellApiClassDefault
 export default class Explainable extends ShellApiWithMongoClass {
@@ -97,7 +98,7 @@ export default class Explainable extends ShellApiWithMongoClass {
   @apiVersions([1])
   @returnsPromise
   async find(
-    query?: Document,
+    query?: MQLQuery,
     projection?: Document,
     options: FindOptions = {}
   ): Promise<ExplainableCursor> {
@@ -107,14 +108,14 @@ export default class Explainable extends ShellApiWithMongoClass {
     return new ExplainableCursor(this._mongo, cursor, this._verbosity);
   }
 
-  async aggregate(pipeline: Document[], options: Document): Promise<Document>;
-  async aggregate(...stages: Document[]): Promise<Document>;
+  async aggregate(pipeline: MQLPipeline, options: Document): Promise<Document>;
+  async aggregate(...stages: MQLPipeline): Promise<Document>;
   @returnsPromise
   @apiVersions([1])
   async aggregate(...args: any[]): Promise<Document> {
     this._emitExplainableApiCall('aggregate', { args });
     let options: Document;
-    let pipeline: Document[];
+    let pipeline: MQLPipeline;
     if (Array.isArray(args[0])) {
       pipeline = args[0];
       options = args[1] ?? {};
@@ -147,17 +148,17 @@ export default class Explainable extends ShellApiWithMongoClass {
   }
 
   async distinct(field: string): Promise<Document>;
-  async distinct(field: string, query: Document): Promise<Document>;
+  async distinct(field: string, query: MQLQuery): Promise<Document>;
   async distinct(
     field: string,
-    query: Document,
+    query: MQLQuery,
     options: DistinctOptions
   ): Promise<Document>;
   @returnsPromise
   @apiVersions([1])
   async distinct(
     field: string,
-    query?: Document,
+    query?: MQLQuery,
     options: DistinctOptions = {}
   ): Promise<Document> {
     this._emitExplainableApiCall('distinct', { field, query, options });
@@ -182,7 +183,7 @@ export default class Explainable extends ShellApiWithMongoClass {
   @returnsPromise
   @apiVersions([1])
   async findOneAndDelete(
-    filter: Document,
+    filter: MQLQuery,
     options: FindOneAndDeleteOptions = {}
   ): Promise<Document | null> {
     this._emitExplainableApiCall('findOneAndDelete', { filter, options });
@@ -195,8 +196,8 @@ export default class Explainable extends ShellApiWithMongoClass {
   @returnsPromise
   @apiVersions([1])
   async findOneAndReplace(
-    filter: Document,
-    replacement: Document,
+    filter: MQLQuery,
+    replacement: MQLDocument,
     options: FindAndModifyShellOptions<FindOneAndReplaceOptions> = {}
   ): Promise<Document> {
     this._emitExplainableApiCall('findOneAndReplace', { filter, options });
@@ -209,8 +210,8 @@ export default class Explainable extends ShellApiWithMongoClass {
   @returnsPromise
   @apiVersions([1])
   async findOneAndUpdate(
-    filter: Document,
-    update: Document,
+    filter: MQLQuery,
+    update: MQLDocument,
     options: FindAndModifyShellOptions<FindOneAndUpdateOptions> = {}
   ): Promise<Document> {
     this._emitExplainableApiCall('findOneAndUpdate', { filter, options });
@@ -223,7 +224,7 @@ export default class Explainable extends ShellApiWithMongoClass {
   @returnsPromise
   @apiVersions([1])
   async remove(
-    query: Document,
+    query: MQLQuery,
     options: boolean | RemoveShellOptions = {}
   ): Promise<Document> {
     this._emitExplainableApiCall('remove', { query, options });

packages/shell-api/src/helpers.ts

@@ -32,6 +32,7 @@ import type { AbstractCursor } from './abstract-cursor';
 import type ChangeStreamCursor from './change-stream-cursor';
 import type { ShellBson } from './shell-bson';
 import { inspect } from 'util';
+import type { MQLPipeline, MQLQuery } from './mql-types';
 
 /**
  * Helper method to adapt aggregation pipeline options.
@@ -882,7 +883,7 @@ export async function iterate(
 
 // This is only used by collection.findAndModify() itself.
 export type FindAndModifyMethodShellOptions = {
-  query: Document;
+  query: MQLQuery;
   sort?: (
     | FindOneAndDeleteOptions
     | FindOneAndReplaceOptions
@@ -1111,7 +1112,9 @@ export function isValidCollectionName(name: string): boolean {
   return !!name && !/[$\0]/.test(name);
 }
 
-export function shouldRunAggregationImmediately(pipeline: Document[]): boolean {
+export function shouldRunAggregationImmediately(
+  pipeline: MQLPipeline
+): boolean {
   return pipeline.some((stage) =>
     Object.keys(stage).some(
       (stageName) => stageName === '$merge' || stageName === '$out'

packages/shell-api/src/mongo.ts

@@ -67,6 +67,7 @@ import type { LogEntry } from './log-entry';
 import { parseAnyLogEntry } from './log-entry';
 import type { CollectionWithSchema } from './collection';
 import type { ShellBson } from './shell-bson';
+import type { MQLPipeline } from './mql-types';
 
 /* Utility, inverse of Readonly<T> */
 type Mutable<T> = {
@@ -845,7 +846,7 @@ export default class Mongo<
   @apiVersions([1])
   @returnsPromise
   async watch(
-    pipeline: Document[] | ChangeStreamOptions = [],
+    pipeline: MQLPipeline | ChangeStreamOptions = [],
     options: ChangeStreamOptions = {}
   ): Promise<ChangeStreamCursor> {
     if (!Array.isArray(pipeline)) {

packages/shell-api/src/mql-types.ts

@@ -0,0 +1,7 @@
+import type { Document } from '@mongosh/service-provider-core';
+
+export type MQLQuery = Document;
+
+export type MQLPipeline = Document[];
+
+export type MQLDocument = Document;

packages/shell-api/src/plan-cache.ts

@@ -11,6 +11,7 @@ import type { CollectionWithSchema } from './collection';
 import { asPrintable, ServerVersions } from './enums';
 import { MongoshDeprecatedError } from '@mongosh/errors';
 import type Mongo from './mongo';
+import type { MQLPipeline, MQLQuery } from './mql-types';
 
 @shellApiClassDefault
 export default class PlanCache extends ShellApiWithMongoClass {
@@ -41,7 +42,7 @@ export default class PlanCache extends ShellApiWithMongoClass {
   @returnsPromise
   @apiVersions([])
   async clearPlansByQuery(
-    query: Document,
+    query: MQLQuery,
     projection?: Document,
     sort?: Document
   ): Promise<Document> {
@@ -58,7 +59,7 @@ export default class PlanCache extends ShellApiWithMongoClass {
   @serverVersions(['4.4.0', ServerVersions.latest])
   @returnsPromise
   @apiVersions([])
-  async list(pipeline?: Document[]): Promise<Document[]> {
+  async list(pipeline?: MQLPipeline): Promise<Document[]> {
     const p = pipeline || [];
     const agg = await this._collection.aggregate([
       { $planCacheStats: {} },