mongoose 8.18.3 → 8.19.0

package/types/models.d.ts

@@ -58,6 +58,7 @@ declare module 'mongoose' {
   interface HydrateOptions {
     setters?: boolean;
     hydratedPopulatedDocs?: boolean;
+    virtuals?: boolean;
   }
 
   interface InsertManyOptions extends
@@ -260,6 +261,12 @@ declare module 'mongoose' {
     hint?: mongodb.Hint;
   }
 
+  type HasLeanOption<TSchema> = 'lean' extends keyof ObtainSchemaGeneric<TSchema, 'TSchemaOptions'> ?
+    ObtainSchemaGeneric<TSchema, 'TSchemaOptions'>['lean'] extends Record<string, any> ?
+      true :
+      ObtainSchemaGeneric<TSchema, 'TSchemaOptions'>['lean'] :
+    false;
+
   /**
    * Models are fancy constructors compiled from `Schema` definitions.
    * An instance of a model is called a document.
@@ -480,11 +487,25 @@ declare module 'mongoose' {
       id: any,
       projection?: ProjectionType<TRawDocType> | null,
       options?: QueryOptions<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
     findById<ResultDoc = THydratedDocumentType>(
       id: any,
       projection?: ProjectionType<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Finds one document. */
     findOne<ResultDoc = THydratedDocumentType>(
@@ -503,14 +524,35 @@ declare module 'mongoose' {
       filter?: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null,
       options?: QueryOptions<TRawDocType> & mongodb.Abortable | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
     findOne<ResultDoc = THydratedDocumentType>(
       filter?: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
     findOne<ResultDoc = THydratedDocumentType>(
       filter?: RootFilterQuery<TRawDocType>
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOne', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
 
     /**
      * Shortcut for creating a new Document from existing raw data, pre-saved in the DB.
@@ -734,16 +776,44 @@ declare module 'mongoose' {
       filter: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null | undefined,
       options?: QueryOptions<TRawDocType> & mongodb.Abortable | null | undefined
-    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[],
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
     find<ResultDoc = THydratedDocumentType>(
       filter: RootFilterQuery<TRawDocType>,
       projection?: ProjectionType<TRawDocType> | null | undefined
-    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[],
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
     find<ResultDoc = THydratedDocumentType>(
       filter: RootFilterQuery<TRawDocType>
-    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[],
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
     find<ResultDoc = THydratedDocumentType>(
-    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[],
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Creates a `findByIdAndDelete` query, filtering by the given `_id`. */
     findByIdAndDelete<ResultDoc = THydratedDocumentType>(
@@ -760,11 +830,25 @@ declare module 'mongoose' {
     findByIdAndDelete<ResultDoc = THydratedDocumentType>(
       id: mongodb.ObjectId | any,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
-    ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndDelete', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? ModifyResult<TRawDocType> : ModifyResult<ResultDoc>,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
     findByIdAndDelete<ResultDoc = THydratedDocumentType>(
       id?: mongodb.ObjectId | any,
       options?: QueryOptions<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndDelete', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Creates a `findOneAndUpdate` query, filtering by the given `_id`. */
     findByIdAndUpdate<ResultDoc = THydratedDocumentType>(
@@ -795,21 +879,49 @@ declare module 'mongoose' {
       id: mongodb.ObjectId | any,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
-    ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? ModifyResult<TRawDocType> : ModifyResult<ResultDoc>,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findByIdAndUpdate<ResultDoc = THydratedDocumentType>(
       id: mongodb.ObjectId | any,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { upsert: true } & ReturnsNewDoc
-    ): QueryWithHelpers<ResultDoc, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType : ResultDoc,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findByIdAndUpdate<ResultDoc = THydratedDocumentType>(
       id?: mongodb.ObjectId | any,
       update?: UpdateQuery<TRawDocType>,
       options?: QueryOptions<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findByIdAndUpdate<ResultDoc = THydratedDocumentType>(
       id: mongodb.ObjectId | any,
       update: UpdateQuery<TRawDocType>
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Creates a `findOneAndDelete` query: atomically finds the given document, deletes it, and returns the document as it was before deletion. */
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
@@ -826,11 +938,25 @@ declare module 'mongoose' {
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
       filter: RootFilterQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
-    ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndDelete', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? ModifyResult<TRawDocType> : ModifyResult<ResultDoc>,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
       filter?: RootFilterQuery<TRawDocType> | null,
       options?: QueryOptions<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndDelete', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Creates a `findOneAndReplace` query: atomically finds the given document and replaces it with `replacement`. */
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
@@ -849,17 +975,38 @@ declare module 'mongoose' {
       filter: RootFilterQuery<TRawDocType>,
       replacement: TRawDocType | AnyObject,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
-    ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndReplace', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? ModifyResult<TRawDocType> : ModifyResult<ResultDoc>,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
       filter: RootFilterQuery<TRawDocType>,
       replacement: TRawDocType | AnyObject,
       options: QueryOptions<TRawDocType> & { upsert: true } & ReturnsNewDoc
-    ): QueryWithHelpers<ResultDoc, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndReplace', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType : ResultDoc,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
       filter?: RootFilterQuery<TRawDocType>,
       replacement?: TRawDocType | AnyObject,
       options?: QueryOptions<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndReplace', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Creates a `findOneAndUpdate` query: atomically find the first document that matches `filter` and apply `update`. */
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
@@ -890,17 +1037,38 @@ declare module 'mongoose' {
       filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true }
-    ): QueryWithHelpers<ModifyResult<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? ModifyResult<TRawDocType> : ModifyResult<ResultDoc>,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
       filter: RootFilterQuery<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
       options: QueryOptions<TRawDocType> & { upsert: true } & ReturnsNewDoc
-    ): QueryWithHelpers<ResultDoc, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType : ResultDoc,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
       filter?: RootFilterQuery<TRawDocType>,
       update?: UpdateQuery<TRawDocType>,
       options?: QueryOptions<TRawDocType> | null
-    ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, TRawDocType, 'findOneAndUpdate', TInstanceMethods & TVirtuals>;
+    ): QueryWithHelpers<
+      HasLeanOption<TSchema> extends true ? TRawDocType | null : ResultDoc | null,
+      ResultDoc,
+      TQueryHelpers,
+      TRawDocType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
 
     /** Creates a `replaceOne` query: finds the first document that matches `filter` and replaces it with `replacement`. */
     replaceOne<ResultDoc = THydratedDocumentType>(
@@ -936,9 +1104,9 @@ declare module 'mongoose' {
     where<ResultDoc = THydratedDocumentType>(
       path: string,
       val?: any
-    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods>;
+    ): QueryWithHelpers<HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[], ResultDoc, TQueryHelpers, TRawDocType, 'find', TInstanceMethods>;
     where<ResultDoc = THydratedDocumentType>(obj: object): QueryWithHelpers<
-      Array<ResultDoc>,
+      HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[],
       ResultDoc,
       TQueryHelpers,
       TRawDocType,
@@ -946,7 +1114,7 @@ declare module 'mongoose' {
       TInstanceMethods & TVirtuals
     >;
     where<ResultDoc = THydratedDocumentType>(): QueryWithHelpers<
-      Array<ResultDoc>,
+      HasLeanOption<TSchema> extends true ? TRawDocType[] : ResultDoc[],
       ResultDoc,
       TQueryHelpers,
       TRawDocType,

package/types/query.d.ts

@@ -12,9 +12,9 @@ declare module 'mongoose' {
    */
   type RootFilterQuery<T> = FilterQuery<T> | Query<any, any> | Types.ObjectId;
 
-  type FilterQuery<T> = {
-    [P in keyof T]?: Condition<T[P]>;
-  } & RootQuerySelector<T> & { _id?: Condition<string>; };
+  type FilterQuery<T> = IsItRecordAndNotAny<T> extends true ?
+    ({ [P in keyof T]?: Condition<T[P]>; } & RootQuerySelector<T> & { _id?: Condition<string>; }) :
+    FilterQuery<Record<string, any>>;
 
   type MongooseBaseQueryOptionKeys =
     | 'context'
@@ -120,6 +120,17 @@ declare module 'mongoose' {
     updatedAt?: boolean;
   }
 
+  // Options that can be passed to Query.prototype.lean()
+  interface LeanOptions {
+    // Set to false to strip out the version key
+    versionKey?: boolean;
+    // Transform the result document in place. `doc` is the raw document being transformed.
+    // Typed as `Record<string, unknown>` because TypeScript gets confused when handling Document.prototype.deleteOne()
+    // and other document methods that try to infer the raw doc type from the Document class.
+    transform?: (doc: Record<string, unknown>) => void;
+    [key: string]: any;
+  }
+
   interface QueryOptions<DocType = unknown> extends
     PopulateOption,
     SessionOption {
@@ -134,7 +145,7 @@ declare module 'mongoose' {
     /**
      * If truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document.
      */
-    lean?: boolean | Record<string, any>;
+    lean?: boolean | LeanOptions;
     limit?: number;
     maxTimeMS?: number;
     multi?: boolean;
@@ -231,7 +242,7 @@ declare module 'mongoose' {
     : MergeType<ResultType, Paths>;
 
   class Query<ResultType, DocType, THelpers = {}, RawDocType = unknown, QueryOp = 'find', TDocOverrides = Record<string, never>> implements SessionOperation {
-    _mongooseOptions: QueryOptions<DocType>;
+    _mongooseOptions: QueryOptions<RawDocType>;
 
     /**
      * Returns a wrapper around a [mongodb driver cursor](https://mongodb.github.io/node-mongodb-native/4.9/classes/FindCursor.html).
@@ -310,14 +321,14 @@ declare module 'mongoose' {
     /** Specifies this query as a `countDocuments` query. */
     countDocuments(
       criteria?: RootFilterQuery<RawDocType>,
-      options?: QueryOptions<DocType>
+      options?: QueryOptions<RawDocType>
     ): QueryWithHelpers<number, DocType, THelpers, RawDocType, 'countDocuments', TDocOverrides>;
 
     /**
      * Returns a wrapper around a [mongodb driver cursor](https://mongodb.github.io/node-mongodb-native/4.9/classes/FindCursor.html).
      * A QueryCursor exposes a Streams3 interface, as well as a `.next()` function.
      */
-    cursor(options?: QueryOptions<DocType>): Cursor<Unpacked<ResultType>, QueryOptions<DocType>>;
+    cursor(options?: QueryOptions<RawDocType>): Cursor<Unpacked<ResultType>, QueryOptions<RawDocType>>;
 
     /**
      * Declare and/or execute this query as a `deleteMany()` operation. Works like
@@ -326,7 +337,7 @@ declare module 'mongoose' {
      */
     deleteMany(
       filter?: RootFilterQuery<RawDocType>,
-      options?: QueryOptions<DocType>
+      options?: QueryOptions<RawDocType>
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'deleteMany', TDocOverrides>;
     deleteMany(filter: RootFilterQuery<RawDocType>): QueryWithHelpers<
       any,
@@ -345,7 +356,7 @@ declare module 'mongoose' {
      */
     deleteOne(
       filter?: RootFilterQuery<RawDocType>,
-      options?: QueryOptions<DocType>
+      options?: QueryOptions<RawDocType>
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'deleteOne', TDocOverrides>;
     deleteOne(filter: RootFilterQuery<RawDocType>): QueryWithHelpers<
       any,
@@ -361,7 +372,7 @@ declare module 'mongoose' {
     distinct<DocKey extends string, ResultType = unknown>(
       field: DocKey,
       filter?: RootFilterQuery<RawDocType>,
-      options?: QueryOptions<DocType>
+      options?: QueryOptions<RawDocType>
     ): QueryWithHelpers<
       Array<
         DocKey extends keyof WithLevel1NestedPaths<DocType>
@@ -390,7 +401,7 @@ declare module 'mongoose' {
     equals(val: any): this;
 
     /** Creates a `estimatedDocumentCount` query: counts the number of documents in the collection. */
-    estimatedDocumentCount(options?: QueryOptions<DocType>): QueryWithHelpers<
+    estimatedDocumentCount(options?: QueryOptions<RawDocType>): QueryWithHelpers<
       number,
       DocType,
       THelpers,
@@ -415,7 +426,7 @@ declare module 'mongoose' {
     find(
       filter: RootFilterQuery<RawDocType>,
       projection?: ProjectionType<RawDocType> | null,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<Array<DocType>, DocType, THelpers, RawDocType, 'find', TDocOverrides>;
     find(
       filter: RootFilterQuery<RawDocType>,
@@ -430,7 +441,7 @@ declare module 'mongoose' {
     findOne(
       filter?: RootFilterQuery<RawDocType>,
       projection?: ProjectionType<RawDocType> | null,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOne', TDocOverrides>;
     findOne(
       filter?: RootFilterQuery<RawDocType>,
@@ -443,24 +454,24 @@ declare module 'mongoose' {
     /** Creates a `findOneAndDelete` query: atomically finds the given document, deletes it, and returns the document as it was before deletion. */
     findOneAndDelete(
       filter?: RootFilterQuery<RawDocType>,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | 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: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType>,
-      options: QueryOptions<DocType> & { includeResultMetadata: true }
+      options: QueryOptions<RawDocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<ModifyResult<DocType>, DocType, THelpers, RawDocType, 'findOneAndUpdate', TDocOverrides>;
     findOneAndUpdate(
       filter: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType>,
-      options: QueryOptions<DocType> & { upsert: true } & ReturnsNewDoc
+      options: QueryOptions<RawDocType> & { upsert: true } & ReturnsNewDoc
     ): QueryWithHelpers<DocType, DocType, THelpers, RawDocType, 'findOneAndUpdate', TDocOverrides>;
     findOneAndUpdate(
       filter: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType>,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOneAndUpdate', TDocOverrides>;
     findOneAndUpdate(
       update: UpdateQuery<RawDocType>
@@ -471,7 +482,7 @@ declare module 'mongoose' {
     findById(
       id: mongodb.ObjectId | any,
       projection?: ProjectionType<RawDocType> | null,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOne', TDocOverrides>;
     findById(
       id: mongodb.ObjectId | any,
@@ -484,28 +495,28 @@ declare module 'mongoose' {
     /** Creates a `findByIdAndDelete` query, filtering by the given `_id`. */
     findByIdAndDelete(
       id: mongodb.ObjectId | any,
-      options: QueryOptions<DocType> & { includeResultMetadata: true }
+      options: QueryOptions<RawDocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<ModifyResult<DocType>, DocType, THelpers, RawDocType, 'findOneAndDelete', TDocOverrides>;
     findByIdAndDelete(
       id?: mongodb.ObjectId | any,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOneAndDelete', TDocOverrides>;
 
     /** Creates a `findOneAndUpdate` query, filtering by the given `_id`. */
     findByIdAndUpdate(
       id: mongodb.ObjectId | any,
       update: UpdateQuery<RawDocType>,
-      options: QueryOptions<DocType> & { includeResultMetadata: true }
+      options: QueryOptions<RawDocType> & { includeResultMetadata: true }
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'findOneAndUpdate', TDocOverrides>;
     findByIdAndUpdate(
       id: mongodb.ObjectId | any,
       update: UpdateQuery<RawDocType>,
-      options: QueryOptions<DocType> & { upsert: true } & ReturnsNewDoc
+      options: QueryOptions<RawDocType> & { upsert: true } & ReturnsNewDoc
     ): QueryWithHelpers<DocType, DocType, THelpers, RawDocType, 'findOneAndUpdate', TDocOverrides>;
     findByIdAndUpdate(
       id?: mongodb.ObjectId | any,
       update?: UpdateQuery<RawDocType>,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<DocType | null, DocType, THelpers, RawDocType, 'findOneAndUpdate', TDocOverrides>;
     findByIdAndUpdate(
       id: mongodb.ObjectId | any,
@@ -526,7 +537,7 @@ declare module 'mongoose' {
     getFilter(): FilterQuery<RawDocType>;
 
     /** Gets query options. */
-    getOptions(): QueryOptions<DocType>;
+    getOptions(): QueryOptions<RawDocType>;
 
     /** Gets a list of paths to be populated by this query */
     getPopulatedPaths(): Array<string>;
@@ -559,8 +570,18 @@ declare module 'mongoose' {
     j(val: boolean | null): this;
 
     /** Sets the lean option. */
+    lean(): QueryWithHelpers<
+      ResultType extends null
+        ? GetLeanResultType<RawDocType, ResultType, QueryOp> | null
+        : GetLeanResultType<RawDocType, ResultType, QueryOp>,
+      DocType,
+      THelpers,
+      RawDocType,
+      QueryOp,
+      TDocOverrides
+      >;
     lean(
-      val?: boolean | any
+      val: true | LeanOptions
     ): QueryWithHelpers<
       ResultType extends null
         ? GetLeanResultType<RawDocType, ResultType, QueryOp> | null
@@ -571,8 +592,32 @@ declare module 'mongoose' {
       QueryOp,
       TDocOverrides
       >;
+    lean(
+      val: false
+    ): QueryWithHelpers<
+      ResultType extends AnyArray<any>
+        ? DocType[]
+        : ResultType extends null
+          ? DocType | null
+          : DocType,
+      DocType,
+      THelpers,
+      RawDocType,
+      QueryOp,
+      TDocOverrides
+      >;
+    lean<LeanResultType>(): QueryWithHelpers<
+      ResultType extends null
+        ? LeanResultType | null
+        : LeanResultType,
+      DocType,
+      THelpers,
+      RawDocType,
+      QueryOp,
+      TDocOverrides
+      >;
     lean<LeanResultType>(
-      val?: boolean | any
+      val: boolean | LeanOptions
     ): QueryWithHelpers<
       ResultType extends null
         ? LeanResultType | null
@@ -626,7 +671,7 @@ declare module 'mongoose' {
      * Getter/setter around the current mongoose-specific options for this query
      * Below are the current Mongoose-specific options.
      */
-    mongooseOptions(val?: QueryOptions<DocType>): QueryOptions<DocType>;
+    mongooseOptions(val?: QueryOptions<RawDocType>): QueryOptions<RawDocType>;
 
     /** Specifies a `$ne` query condition. When called with one argument, the most recent path passed to `where()` is used. */
     ne<K = string>(path: K, val: any): this;
@@ -734,7 +779,7 @@ declare module 'mongoose' {
     replaceOne(
       filter?: RootFilterQuery<RawDocType>,
       replacement?: DocType | AnyObject,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<any, DocType, THelpers, RawDocType, 'replaceOne', TDocOverrides>;
 
     /**
@@ -800,7 +845,7 @@ declare module 'mongoose' {
     set(path: string | Record<string, unknown>, value?: any): this;
 
     /** Sets query options. Some options only make sense for certain operations. */
-    setOptions(options: QueryOptions<DocType>, overwrite?: boolean): this;
+    setOptions(options: QueryOptions<RawDocType>, overwrite?: boolean): this;
 
     /** Sets the query conditions to the provided JSON object. */
     setQuery(val: FilterQuery<RawDocType> | null): void;
@@ -848,7 +893,7 @@ declare module 'mongoose' {
     updateMany(
       filter: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType> | UpdateWithAggregationPipeline,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<UpdateWriteOpResult, DocType, THelpers, RawDocType, 'updateMany', TDocOverrides>;
     updateMany(
       update: UpdateQuery<RawDocType> | UpdateWithAggregationPipeline
@@ -861,7 +906,7 @@ declare module 'mongoose' {
     updateOne(
       filter: RootFilterQuery<RawDocType>,
       update: UpdateQuery<RawDocType> | UpdateWithAggregationPipeline,
-      options?: QueryOptions<DocType> | null
+      options?: QueryOptions<RawDocType> | null
     ): QueryWithHelpers<UpdateWriteOpResult, DocType, THelpers, RawDocType, 'updateOne', TDocOverrides>;
     updateOne(
       update: UpdateQuery<RawDocType> | UpdateWithAggregationPipeline

package/types/schemaoptions.d.ts

@@ -58,6 +58,9 @@ declare module 'mongoose' {
     /** Arbitrary options passed to `createCollection()` */
     collectionOptions?: mongodb.CreateCollectionOptions;
 
+    /** Default lean options for queries */
+    lean?: boolean | LeanOptions;
+
     /** The timeseries option to use when creating the model's collection. */
     timeseries?: mongodb.TimeSeriesCollectionOptions;