mongoose 8.5.5 → 8.6.0

package/lib/cursor/changeStream.js

@@ -33,15 +33,18 @@ class ChangeStream extends EventEmitter {
       );
     }
 
-    // This wrapper is necessary because of buffering.
-    changeStreamThunk((err, driverChangeStream) => {
-      if (err != null) {
-        this.emit('error', err);
-        return;
-      }
+    this.$driverChangeStreamPromise = new Promise((resolve, reject) => {
+      // This wrapper is necessary because of buffering.
+      changeStreamThunk((err, driverChangeStream) => {
+        if (err != null) {
+          this.emit('error', err);
+          return reject(err);
+        }
 
-      this.driverChangeStream = driverChangeStream;
-      this.emit('ready');
+        this.driverChangeStream = driverChangeStream;
+        this.emit('ready');
+        resolve();
+      });
     });
   }
 
@@ -53,20 +56,23 @@ class ChangeStream extends EventEmitter {
     this.bindedEvents = true;
 
     if (this.driverChangeStream == null) {
-      this.once('ready', () => {
-        this.driverChangeStream.on('close', () => {
-          this.closed = true;
-        });
+      this.$driverChangeStreamPromise.then(
+        () => {
+          this.driverChangeStream.on('close', () => {
+            this.closed = true;
+          });
 
-        driverChangeStreamEvents.forEach(ev => {
-          this.driverChangeStream.on(ev, data => {
-            if (data != null && data.fullDocument != null && this.options && this.options.hydrate) {
-              data.fullDocument = this.options.model.hydrate(data.fullDocument);
-            }
-            this.emit(ev, data);
+          driverChangeStreamEvents.forEach(ev => {
+            this.driverChangeStream.on(ev, data => {
+              if (data != null && data.fullDocument != null && this.options && this.options.hydrate) {
+                data.fullDocument = this.options.model.hydrate(data.fullDocument);
+              }
+              this.emit(ev, data);
+            });
           });
-        });
-      });
+        },
+        () => {} // No need to register events if opening change stream failed
+      );
 
       return;
     }
@@ -142,8 +148,12 @@ class ChangeStream extends EventEmitter {
     this.closed = true;
     if (this.driverChangeStream) {
       return this.driverChangeStream.close();
+    } else {
+      return this.$driverChangeStreamPromise.then(
+        () => this.driverChangeStream.close(),
+        () => {} // No need to close if opening the change stream failed
+      );
     }
-    return Promise.resolve();
   }
 }
 

package/lib/cursor/queryCursor.js

@@ -10,6 +10,7 @@ const eachAsync = require('../helpers/cursor/eachAsync');
 const helpers = require('../queryHelpers');
 const kareem = require('kareem');
 const immediate = require('../helpers/immediate');
+const { once } = require('node:events');
 const util = require('util');
 
 /**
@@ -42,6 +43,7 @@ function QueryCursor(query) {
   this.cursor = null;
   this.skipped = false;
   this.query = query;
+  this._closed = false;
   const model = query.model;
   this._mongooseOptions = {};
   this._transforms = [];
@@ -135,6 +137,25 @@ QueryCursor.prototype._read = function() {
   });
 };
 
+/**
+ * Returns the underlying cursor from the MongoDB Node driver that this cursor uses.
+ *
+ * @method getDriverCursor
+ * @memberOf QueryCursor
+ * @returns {Cursor} MongoDB Node driver cursor instance
+ * @instance
+ * @api public
+ */
+
+QueryCursor.prototype.getDriverCursor = async function getDriverCursor() {
+  if (this.cursor) {
+    return this.cursor;
+  }
+
+  await once(this, 'cursor');
+  return this.cursor;
+};
+
 /**
  * Registers a transform function which subsequently maps documents retrieved
  * via the streams interface or `.next()`
@@ -209,6 +230,7 @@ QueryCursor.prototype.close = async function close() {
   }
   try {
     await this.cursor.close();
+    this._closed = true;
     this.emit('close');
   } catch (error) {
     this.listeners('error').length > 0 && this.emit('error', error);
@@ -246,6 +268,9 @@ QueryCursor.prototype.next = async function next() {
   if (typeof arguments[0] === 'function') {
     throw new MongooseError('QueryCursor.prototype.next() no longer accepts a callback');
   }
+  if (this._closed) {
+    throw new MongooseError('Cannot call `next()` on a closed cursor');
+  }
   return new Promise((resolve, reject) => {
     _next(this, function(error, doc) {
       if (error) {

package/lib/model.js

@@ -2115,17 +2115,21 @@ Model.countDocuments = function countDocuments(conditions, options) {
  *
  * @param {String} field
  * @param {Object} [conditions] optional
+ * @param {Object} [options] optional
  * @return {Query}
  * @api public
  */
 
-Model.distinct = function distinct(field, conditions) {
+Model.distinct = function distinct(field, conditions, options) {
   _checkContext(this, 'distinct');
-  if (typeof arguments[0] === 'function' || typeof arguments[1] === 'function') {
+  if (typeof arguments[0] === 'function' || typeof arguments[1] === 'function' || typeof arguments[2] === 'function') {
     throw new MongooseError('Model.distinct() no longer accepts a callback');
   }
 
   const mq = new this.Query({}, {}, this, this.$__collection);
+  if (options != null) {
+    mq.setOptions(options);
+  }
 
   return mq.distinct(field, conditions);
 };

package/lib/query.js

@@ -2777,7 +2777,7 @@ Query.prototype.estimatedDocumentCount = function(options) {
   this.op = 'estimatedDocumentCount';
   this._validateOp();
 
-  if (typeof options === 'object' && options != null) {
+  if (options != null) {
     this.setOptions(options);
   }
 
@@ -2836,7 +2836,7 @@ Query.prototype.countDocuments = function(conditions, options) {
     this.merge(conditions);
   }
 
-  if (typeof options === 'object' && options != null) {
+  if (options != null) {
     this.setOptions(options);
   }
 
@@ -2874,21 +2874,24 @@ Query.prototype.__distinct = async function __distinct() {
  *
  * #### Example:
  *
+ *     distinct(field, conditions, options)
  *     distinct(field, conditions)
  *     distinct(field)
  *     distinct()
  *
  * @param {String} [field]
  * @param {Object|Query} [filter]
+ * @param {Object} [options]
  * @return {Query} this
  * @see distinct https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct/
  * @api public
  */
 
-Query.prototype.distinct = function(field, conditions) {
+Query.prototype.distinct = function(field, conditions, options) {
   if (typeof field === 'function' ||
       typeof conditions === 'function' ||
-      typeof arguments[2] === 'function') {
+      typeof options === 'function' ||
+      typeof arguments[3] === 'function') {
     throw new MongooseError('Query.prototype.distinct() no longer accepts a callback');
   }
 
@@ -2907,6 +2910,10 @@ Query.prototype.distinct = function(field, conditions) {
     this._distinct = field;
   }
 
+  if (options != null) {
+    this.setOptions(options);
+  }
+
   return this;
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "8.5.5",
+  "version": "8.6.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -21,7 +21,7 @@
   "dependencies": {
     "bson": "^6.7.0",
     "kareem": "2.6.3",
-    "mongodb": "6.7.0",
+    "mongodb": "6.8.0",
     "mpath": "0.9.0",
     "mquery": "5.0.0",
     "ms": "2.1.3",
@@ -67,7 +67,7 @@
     "tsd": "0.31.1",
     "typescript": "5.5.4",
     "uuid": "10.0.0",
-    "webpack": "5.93.0"
+    "webpack": "5.94.0"
   },
   "directories": {
     "lib": "./lib/mongoose"

package/types/document.d.ts

@@ -22,7 +22,7 @@ declare module 'mongoose' {
     constructor(doc?: any);
 
     /** This documents _id. */
-    _id?: T;
+    _id: T;
 
     /** This documents __v. */
     __v?: any;
@@ -259,11 +259,14 @@ declare module 'mongoose' {
     set(value: string | Record<string, any>): this;
 
     /** The return value of this method is used in calls to JSON.stringify(doc). */
+    toJSON(options?: ToObjectOptions & { flattenMaps?: true }): FlattenMaps<Require_id<DocType>>;
+    toJSON(options: ToObjectOptions & { flattenMaps: false }): Require_id<DocType>;
     toJSON<T = Require_id<DocType>>(options?: ToObjectOptions & { flattenMaps?: true }): FlattenMaps<T>;
     toJSON<T = Require_id<DocType>>(options: ToObjectOptions & { flattenMaps: false }): T;
 
     /** Converts this document into a plain-old JavaScript object ([POJO](https://masteringjs.io/tutorials/fundamentals/pojo)). */
-    toObject<T = Require_id<DocType>>(options?: ToObjectOptions): Require_id<T>;
+    toObject(options?: ToObjectOptions): Require_id<DocType>;
+    toObject<T>(options?: ToObjectOptions): Require_id<T>;
 
     /** Clears the modified state on the specified path. */
     unmarkModified<T extends keyof DocType>(path: T): void;

package/types/inferrawdoctype.d.ts

@@ -1,4 +1,5 @@
 import {
+  IsPathRequired,
   IsSchemaTypeFromBuiltinClass,
   RequiredPaths,
   OptionalPaths,
@@ -14,7 +15,9 @@ declare module 'mongoose' {
     [
     K in keyof (RequiredPaths<DocDefinition, TSchemaOptions['typeKey']> &
     OptionalPaths<DocDefinition, TSchemaOptions['typeKey']>)
-    ]: ObtainRawDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']>;
+    ]: IsPathRequired<DocDefinition[K], TSchemaOptions['typeKey']> extends true
+      ? ObtainRawDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']>
+      : ObtainRawDocumentPathType<DocDefinition[K], TSchemaOptions['typeKey']> | null;
   }, TSchemaOptions>;
 
   /**

package/types/models.d.ts

@@ -188,7 +188,7 @@ declare module 'mongoose' {
 
   export interface ReplaceOneModel<TSchema = AnyObject> {
     /** The filter to limit the replaced document. */
-    filter: FilterQuery<TSchema>;
+    filter: RootFilterQuery<TSchema>;
     /** The document with which to replace the matched document. */
     replacement: mongodb.WithoutId<TSchema>;
     /** Specifies a collation. */
@@ -203,7 +203,7 @@ declare module 'mongoose' {
 
   export interface UpdateOneModel<TSchema = AnyObject> {
     /** The filter to limit the updated documents. */
-    filter: FilterQuery<TSchema>;
+    filter: RootFilterQuery<TSchema>;
     /** A document or pipeline containing update operators. */
     update: UpdateQuery<TSchema>;
     /** A set of filters specifying to which array elements an update should apply. */
@@ -220,7 +220,7 @@ declare module 'mongoose' {
 
   export interface UpdateManyModel<TSchema = AnyObject> {
     /** The filter to limit the updated documents. */
-    filter: FilterQuery<TSchema>;
+    filter: RootFilterQuery<TSchema>;
     /** A document or pipeline containing update operators. */
     update: UpdateQuery<TSchema>;
     /** A set of filters specifying to which array elements an update should apply. */
@@ -237,7 +237,7 @@ declare module 'mongoose' {
 
   export interface DeleteOneModel<TSchema = AnyObject> {
     /** The filter to limit the deleted documents. */
-    filter: FilterQuery<TSchema>;
+    filter: RootFilterQuery<TSchema>;
     /** Specifies a collation. */
     collation?: mongodb.CollationOptions;
     /** The index to use. If specified, then the query system will only consider plans using the hinted index. */
@@ -246,7 +246,7 @@ declare module 'mongoose' {
 
   export interface DeleteManyModel<TSchema = AnyObject> {
     /** The filter to limit the deleted documents. */
-    filter: FilterQuery<TSchema>;
+    filter: RootFilterQuery<TSchema>;
     /** Specifies a collation. */
     collation?: mongodb.CollationOptions;
     /** The index to use. If specified, then the query system will only consider plans using the hinted index. */
@@ -318,7 +318,7 @@ declare module 'mongoose' {
 
     /** Creates a `countDocuments` query: counts the number of documents that match `filter`. */
     countDocuments(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       options?: (mongodb.CountOptions & MongooseBaseQueryOptions<TRawDocType>) | null
     ): QueryWithHelpers<
       number,
@@ -357,7 +357,7 @@ declare module 'mongoose' {
      * regardless of the `single` option.
      */
     deleteMany(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       options?: (mongodb.DeleteOptions & MongooseBaseQueryOptions<TRawDocType>) | null
     ): QueryWithHelpers<
       mongodb.DeleteResult,
@@ -368,7 +368,7 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     deleteMany(
-      filter: FilterQuery<TRawDocType>
+      filter: RootFilterQuery<TRawDocType>
     ): QueryWithHelpers<
       mongodb.DeleteResult,
       THydratedDocumentType,
@@ -384,7 +384,7 @@ declare module 'mongoose' {
      * `single` option.
      */
     deleteOne(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       options?: (mongodb.DeleteOptions & MongooseBaseQueryOptions<TRawDocType>) | null
     ): QueryWithHelpers<
       mongodb.DeleteResult,
@@ -395,7 +395,7 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     deleteOne(
-      filter: FilterQuery<TRawDocType>
+      filter: RootFilterQuery<TRawDocType>
     ): QueryWithHelpers<
       mongodb.DeleteResult,
       THydratedDocumentType,
@@ -446,7 +446,7 @@ declare module 'mongoose' {
 
     /** Finds one document. */
     findOne<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       projection: ProjectionType<TRawDocType> | null | undefined,
       options: QueryOptions<TRawDocType> & { lean: true }
     ): QueryWithHelpers<
@@ -458,16 +458,16 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     findOne<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null,
       options?: QueryOptions<TRawDocType> | null
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods>;
     findOne<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods>;
     findOne<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>
+      filter?: RootFilterQuery<TRawDocType>
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods>;
 
     /**
@@ -621,7 +621,8 @@ declare module 'mongoose' {
     /** Creates a `distinct` query: returns the distinct values of the given `field` that match `filter`. */
     distinct<DocKey extends string, ResultType = unknown>(
       field: DocKey,
-      filter?: FilterQuery<TRawDocType>
+      filter?: RootFilterQuery<TRawDocType>,
+      options?: QueryOptions<TRawDocType>
     ): QueryWithHelpers<
       Array<
         DocKey extends keyof WithLevel1NestedPaths<TRawDocType>
@@ -650,7 +651,7 @@ declare module 'mongoose' {
      * the given `filter`, and `null` otherwise.
      */
     exists(
-      filter: FilterQuery<TRawDocType>
+      filter: RootFilterQuery<TRawDocType>
     ): QueryWithHelpers<
       { _id: InferId<TRawDocType> } | null,
       THydratedDocumentType,
@@ -662,7 +663,7 @@ declare module 'mongoose' {
 
     /** Creates a `find` query: gets a list of documents that match `filter`. */
     find<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       projection: ProjectionType<TRawDocType> | null | undefined,
       options: QueryOptions<TRawDocType> & { lean: true }
     ): QueryWithHelpers<
@@ -674,16 +675,16 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     find<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null | undefined,
       options?: QueryOptions<TRawDocType> | null | undefined
     ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods>;
     find<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null | undefined
     ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods>;
     find<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>
+      filter: RootFilterQuery<TRawDocType>
     ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods>;
     find<ResultDoc = THydratedDocumentType>(
     ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods>;
@@ -711,7 +712,7 @@ declare module 'mongoose' {
 
     /** Creates a `findOneAndUpdate` query, filtering by the given `_id`. */
     findByIdAndUpdate<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true, lean: true }
     ): QueryWithHelpers<
@@ -756,7 +757,7 @@ declare module 'mongoose' {
 
     /** Creates a `findOneAndDelete` query: atomically finds the given document, deletes it, and returns the document as it was before deletion. */
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { lean: true }
     ): QueryWithHelpers<
       GetLeanResultType<TRawDocType, TRawDocType, 'findOneAndDelete'> | null,
@@ -767,17 +768,17 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndDelete', TInstanceMethods>;
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType> | null,
+      filter?: RootFilterQuery<TRawDocType> | null,
       options?: QueryOptions<TRawDocType> | null
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndDelete', TInstanceMethods>;
 
     /** Creates a `findOneAndReplace` query: atomically finds the given document and replaces it with `replacement`. */
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       replacement: TRawDocType | AnyObject,
       options: QueryOptions<TRawDocType> & { lean: true }
     ): QueryWithHelpers<
@@ -789,24 +790,24 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       replacement: TRawDocType | AnyObject,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndReplace', TInstanceMethods>;
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       replacement: TRawDocType | AnyObject,
       options: QueryOptions<TRawDocType> & { upsert: true } & ReturnsNewDoc
     ): QueryWithHelpers<ResultDoc, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndReplace', TInstanceMethods>;
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       replacement?: TRawDocType | AnyObject,
       options?: QueryOptions<TRawDocType> | null
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndReplace', TInstanceMethods>;
 
     /** Creates a `findOneAndUpdate` query: atomically find the first document that matches `filter` and apply `update`. */
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true, lean: true }
     ): QueryWithHelpers<
@@ -818,7 +819,7 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { lean: true }
     ): QueryWithHelpers<
@@ -830,24 +831,24 @@ declare module 'mongoose' {
       TInstanceMethods
     >;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods>;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
-      filter: FilterQuery<TRawDocType>,
+      filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { upsert: true } & ReturnsNewDoc
     ): QueryWithHelpers<ResultDoc, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods>;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       update?: UpdateQuery<TRawDocType>,
       options?: QueryOptions<TRawDocType> | null
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods>;
 
     /** Creates a `replaceOne` query: finds the first document that matches `filter` and replaces it with `replacement`. */
     replaceOne<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       replacement?: TRawDocType | AnyObject,
       options?: (mongodb.ReplaceOptions & MongooseQueryOptions<TRawDocType>) | null
     ): QueryWithHelpers<UpdateWriteOpResult, ResultDoc, TQueryHelpers, TRawDocType, 'replaceOne', TInstanceMethods>;
@@ -860,14 +861,14 @@ declare module 'mongoose' {
 
     /** Creates a `updateMany` query: updates all documents that match `filter` with `update`. */
     updateMany<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       update?: UpdateQuery<TRawDocType> | UpdateWithAggregationPipeline,
       options?: (mongodb.UpdateOptions & MongooseUpdateQueryOptions<TRawDocType>) | null
     ): QueryWithHelpers<UpdateWriteOpResult, ResultDoc, TQueryHelpers, TRawDocType, 'updateMany', TInstanceMethods>;
 
     /** Creates a `updateOne` query: updates the first document that matches `filter` with `update`. */
     updateOne<ResultDoc = THydratedDocumentType>(
-      filter?: FilterQuery<TRawDocType>,
+      filter?: RootFilterQuery<TRawDocType>,
       update?: UpdateQuery<TRawDocType> | UpdateWithAggregationPipeline,
       options?: (mongodb.UpdateOptions & MongooseUpdateQueryOptions<TRawDocType>) | null
     ): QueryWithHelpers<UpdateWriteOpResult, ResultDoc, TQueryHelpers, TRawDocType, 'updateOne', TInstanceMethods>;

package/types/query.d.ts

@@ -10,9 +10,11 @@ declare module 'mongoose' {
    * { age: { $gte: 30 } }
    * ```
    */
-  type FilterQuery<T> = {
+  type RootFilterQuery<T> = FilterQuery<T> | Query<any, any> | Types.ObjectId;
+
+  type FilterQuery<T> ={
     [P in keyof T]?: Condition<T[P]>;
-  } & RootQuerySelector<T>;
+  } & RootQuerySelector<T> & { _id?: Condition<string>; };
 
   type MongooseBaseQueryOptionKeys =
     | 'context'
@@ -115,8 +117,9 @@ declare module 'mongoose' {
     /** @see https://www.mongodb.com/docs/manual/reference/operator/query/comment/#op._S_comment */
     $comment?: string;
     // we could not find a proper TypeScript generic to support nested queries e.g. 'user.friends.name'
-    // this will mark all unrecognized properties as any (including nested queries)
-    [key: string]: any;
+    // this will mark all unrecognized properties as any (including nested queries) only if
+    // they include a "." (to avoid generically allowing any unexpected keys)
+    [nestedSelector: `${string}.${string}`]: any;
   };
 
   interface QueryTimestampsConfig {
@@ -224,7 +227,7 @@ declare module 'mongoose' {
           : MergeType<ResultType, Paths>
     : MergeType<ResultType, Paths>;
 
-  class Query<ResultType, DocType, THelpers = {}, RawDocType = DocType, QueryOp = 'find', TInstanceMethods = Record<string, never>> implements SessionOperation {
+  class Query<ResultType, DocType, THelpers = {}, RawDocType = unknown, QueryOp = 'find', TInstanceMethods = Record<string, never>> implements SessionOperation {
     _mongooseOptions: MongooseQueryOptions<DocType>;
 
     /**
@@ -303,7 +306,7 @@ declare module 'mongoose' {
 
     /** Specifies this query as a `countDocuments` query. */
     countDocuments(
-      criteria?: FilterQuery<RawDocType>,
+      criteria?: RootFilterQuery<RawDocType>,
       options?: QueryOptions<DocType>
     ): QueryWithHelpers<number, DocType, THelpers, RawDocType, 'countDocuments', TInstanceMethods>;
 
@@ -319,10 +322,10 @@ declare module 'mongoose' {
      * collection, regardless of the value of `single`.
      */
     deleteMany(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       options?: QueryOptions<DocType>
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'deleteMany', TInstanceMethods>;
-    deleteMany(filter: FilterQuery<RawDocType>): QueryWithHelpers<
+    deleteMany(filter: RootFilterQuery<RawDocType>): QueryWithHelpers<
       any,
       DocType,
       THelpers,
@@ -338,10 +341,10 @@ declare module 'mongoose' {
      * option.
      */
     deleteOne(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       options?: QueryOptions<DocType>
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'deleteOne', TInstanceMethods>;
-    deleteOne(filter: FilterQuery<RawDocType>): QueryWithHelpers<
+    deleteOne(filter: RootFilterQuery<RawDocType>): QueryWithHelpers<
       any,
       DocType,
       THelpers,
@@ -354,7 +357,8 @@ declare module 'mongoose' {
     /** Creates a `distinct` query: returns the distinct values of the given `field` that match `filter`. */
     distinct<DocKey extends string, ResultType = unknown>(
       field: DocKey,
-      filter?: FilterQuery<RawDocType>
+      filter?: RootFilterQuery<RawDocType>,
+      options?: QueryOptions<DocType>
     ): QueryWithHelpers<
       Array<
         DocKey extends keyof WithLevel1NestedPaths<DocType>
@@ -406,52 +410,52 @@ declare module 'mongoose' {
 
     /** Creates a `find` query: gets a list of documents that match `filter`. */
     find(
-      filter: FilterQuery<RawDocType>,
+      filter: RootFilterQuery<RawDocType>,
       projection?: ProjectionType<RawDocType> | null,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<Array<DocType>, DocType, THelpers, RawDocType, 'find', TInstanceMethods>;
     find(
-      filter: FilterQuery<RawDocType>,
+      filter: RootFilterQuery<RawDocType>,
       projection?: ProjectionType<RawDocType> | null
     ): QueryWithHelpers<Array<DocType>, DocType, THelpers, RawDocType, 'find', TInstanceMethods>;
     find(
-      filter: FilterQuery<RawDocType>
+      filter: RootFilterQuery<RawDocType>
     ): QueryWithHelpers<Array<DocType>, DocType, THelpers, RawDocType, 'find', TInstanceMethods>;
     find(): QueryWithHelpers<Array<DocType>, DocType, THelpers, RawDocType, 'find', TInstanceMethods>;
 
     /** Declares the query a findOne operation. When executed, returns the first found document. */
     findOne(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       projection?: ProjectionType<RawDocType> | null,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOne', TInstanceMethods>;
     findOne(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       projection?: ProjectionType<RawDocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOne', TInstanceMethods>;
     findOne(
-      filter?: FilterQuery<RawDocType>
+      filter?: RootFilterQuery<RawDocType>
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOne', TInstanceMethods>;
 
     /** Creates a `findOneAndDelete` query: atomically finds the given document, deletes it, and returns the document as it was before deletion. */
     findOneAndDelete(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOneAndDelete'>;
 
     /** Creates a `findOneAndUpdate` query: atomically find the first document that matches `filter` and apply `update`. */
     findOneAndUpdate(
-      filter: FilterQuery<RawDocType>,
+      filter: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType>,
       options: QueryOptions<DocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<ModifyResult<DocType>, DocType, THelpers, RawDocType, 'findOneAndUpdate', TInstanceMethods>;
     findOneAndUpdate(
-      filter: FilterQuery<RawDocType>,
+      filter: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType>,
       options: QueryOptions<DocType> & { upsert: true } & ReturnsNewDoc
     ): QueryWithHelpers<DocType, DocType, THelpers, RawDocType, 'findOneAndUpdate', TInstanceMethods>;
     findOneAndUpdate(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       update?: UpdateQuery<RawDocType>,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOneAndUpdate', TInstanceMethods>;
@@ -548,9 +552,19 @@ declare module 'mongoose' {
     j(val: boolean | null): this;
 
     /** Sets the lean option. */
-    lean<
-      LeanResultType = GetLeanResultType<RawDocType, ResultType, QueryOp>
-    >(
+    lean(
+      val?: boolean | any
+    ): QueryWithHelpers<
+      ResultType extends null
+        ? GetLeanResultType<RawDocType, ResultType, QueryOp> | null
+        : GetLeanResultType<RawDocType, ResultType, QueryOp>,
+      DocType,
+      THelpers,
+      RawDocType,
+      QueryOp,
+      TInstanceMethods
+      >;
+    lean<LeanResultType>(
       val?: boolean | any
     ): QueryWithHelpers<
       ResultType extends null
@@ -592,7 +606,7 @@ declare module 'mongoose' {
     maxTimeMS(ms: number): this;
 
     /** Merges another Query or conditions object into this one. */
-    merge(source: Query<any, any> | FilterQuery<RawDocType>): this;
+    merge(source: RootFilterQuery<RawDocType>): this;
 
     /** Specifies a `$mod` condition, filters documents for documents whose `path` property is a number that is equal to `remainder` modulo `divisor`. */
     mod<K = string>(path: K, val: number): this;
@@ -711,7 +725,7 @@ declare module 'mongoose' {
      * not accept any [atomic](https://www.mongodb.com/docs/manual/tutorial/model-data-for-atomic-operations/#pattern) operators (`$set`, etc.)
      */
     replaceOne(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       replacement?: DocType | AnyObject,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'replaceOne', TInstanceMethods>;
@@ -819,7 +833,7 @@ declare module 'mongoose' {
      * the `multi` option.
      */
     updateMany(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       update?: UpdateQuery<RawDocType> | UpdateWithAggregationPipeline,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<UpdateWriteOpResult, DocType, THelpers, RawDocType, 'updateMany', TInstanceMethods>;
@@ -829,7 +843,7 @@ declare module 'mongoose' {
      * `update()`, except it does not support the `multi` or `overwrite` options.
      */
     updateOne(
-      filter?: FilterQuery<RawDocType>,
+      filter?: RootFilterQuery<RawDocType>,
       update?: UpdateQuery<RawDocType> | UpdateWithAggregationPipeline,
       options?: QueryOptions<DocType> | null
     ): QueryWithHelpers<UpdateWriteOpResult, DocType, THelpers, RawDocType, 'updateOne', TInstanceMethods>;