mongoose 9.9.5 → 9.10.0

package/eslint.config.mjs

@@ -43,6 +43,7 @@ export default defineConfig([
       'no-constant-condition': 'off',
       'no-multi-spaces': 'error',
       'func-call-spacing': 'error',
+      'no-unused-vars': ['error', { ignoreRestSiblings: true }],
       'no-trailing-spaces': 'error',
       'no-undef': 'error',
       'no-unneeded-ternary': 'error',

package/lib/aggregate.js

@@ -810,8 +810,7 @@ Aggregate.prototype.explain = async function explain(verbosity) {
   const postFilter = buildMiddlewareFilter(this.options, 'post');
 
   // Remove middleware option before passing to MongoDB
-  const options = this.options != null ? { ...this.options } : {};
-  delete options.middleware;
+  const { middleware, ...options } = this.options ?? {};
 
   try {
     await model.hooks.execPre('aggregate', this, [], { filter: preFilter });
@@ -925,6 +924,8 @@ Aggregate.prototype.option = function(value) {
  * Sets the `cursor` option and executes this aggregation, returning an aggregation cursor.
  * Cursors are useful if you want to process the results of the aggregation one-at-a-time
  * because the aggregation result is too big to fit into memory.
+ * Creating an aggregation cursor runs pre aggregate hooks, but not post aggregate hooks.
+ * To skip pre aggregate hooks, pass `middleware: false` to `.cursor()`.
  *
  * #### Example:
  *
@@ -935,6 +936,8 @@ Aggregate.prototype.option = function(value) {
  *
  * @param {object} options
  * @param {number} [options.batchSize] set the cursor batch size
+ * @param {boolean|object} [options.middleware=true] set to `false` to skip user-defined pre aggregate middleware
+ * @param {boolean} [options.middleware.pre=true] set to `false` to skip pre aggregate middleware
  * @param {boolean} [options.useMongooseAggCursor] use experimental mongoose-specific aggregation cursor (for `eachAsync()` and other query cursor semantics)
  * @return {AggregationCursor} cursor representing this aggregation
  * @api public
@@ -943,6 +946,11 @@ Aggregate.prototype.option = function(value) {
 
 Aggregate.prototype.cursor = function(options) {
   this._optionsForExec();
+  if (utils.hasUserDefinedProperty(options, 'middleware')) {
+    const { middleware, ...cursorOptions } = options;
+    this.options.middleware = middleware;
+    options = cursorOptions;
+  }
   this.options.cursor = options || {};
   return new AggregationCursor(this); // return this;
 };
@@ -1122,8 +1130,7 @@ Aggregate.prototype.exec = async function exec() {
       throw new MongooseError('Aggregate has empty pipeline');
     }
 
-    const options = clone(_this.options || {});
-    delete options.middleware;
+    const { middleware, ...options } = clone(_this.options || {});
 
     let result;
     try {

package/lib/cursor/aggregationCursor.js

@@ -11,6 +11,7 @@ const immediate = require('../helpers/immediate');
 const kareem = require('kareem');
 const util = require('util');
 const { cursorNextChannel } = require('../tracing');
+const { buildMiddlewareFilter } = require('../helpers/buildMiddlewareFilter');
 
 /**
  * An AggregationCursor is a concurrency primitive for processing aggregation
@@ -49,7 +50,14 @@ function AggregationCursor(agg) {
   this._mongooseOptions = {};
 
   if (connection) {
-    this.cursor = connection.db.aggregate(agg._pipeline, agg.options || {});
+    let options = agg.options || {};
+    if (Object.hasOwn(options, 'middleware')) {
+      // `middleware` is a Mongoose-only option used to skip user hooks; strip
+      // it from the clone passed through to the MongoDB driver.
+      const { middleware, ...driverOptions } = options;
+      options = driverOptions;
+    }
+    this.cursor = connection.db.aggregate(agg._pipeline, options);
     setImmediate(() => this.emit('cursor', this.cursor));
   } else {
     _init(model, this, agg);
@@ -63,7 +71,8 @@ util.inherits(AggregationCursor, Readable);
  */
 
 function _init(model, c, agg) {
-  model.hooks.execPre('aggregate', agg).then(() => onPreComplete(null), err => onPreComplete(err));
+  const preFilter = buildMiddlewareFilter(agg.options, 'pre');
+  model.hooks.execPre('aggregate', agg, [], { filter: preFilter }).then(() => onPreComplete(null), err => onPreComplete(err));
 
   function onPreComplete(err) {
     if (err != null) {
@@ -90,7 +99,14 @@ function _init(model, c, agg) {
 
 function _getRawCursor(model, aggregationCursor, agg) {
   try {
-    const cursor = model.collection.aggregate(agg._pipeline, agg.options || {});
+    let options = agg.options;
+    if (Object.hasOwn(options, 'middleware')) {
+      // `middleware` is a Mongoose-only option used to skip user hooks; strip
+      // it from the clone passed through to the MongoDB driver.
+      const { middleware, ...driverOptions } = options;
+      options = driverOptions;
+    }
+    const cursor = model.collection.aggregate(agg._pipeline, options);
     aggregationCursor.cursor = cursor;
     aggregationCursor.emit('cursor', cursor);
   } catch (err) {

package/lib/cursor/queryCursor.js

@@ -13,6 +13,7 @@ const immediate = require('../helpers/immediate');
 const { once } = require('events');
 const util = require('util');
 const { cursorNextChannel } = require('../tracing');
+const { buildMiddlewareFilter } = require('../helpers/buildMiddlewareFilter');
 
 /**
  * A QueryCursor is a concurrency primitive for processing query results
@@ -21,7 +22,8 @@ const { cursorNextChannel } = require('../tracing');
  * one at a time.
  *
  * QueryCursors execute the model's pre `find` hooks before loading any documents
- * from MongoDB, and the model's post `find` hooks after loading each document.
+ * from MongoDB, and the model's post `find` hooks once per document,
+ * with an array containing that document.
  *
  * Unless you're an advanced user, do **not** instantiate this class directly.
  * Use [`Query#cursor()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.cursor()) instead.
@@ -50,6 +52,7 @@ function QueryCursor(query) {
   this._transforms = [];
   this.model = model;
   this.options = {};
+  this._postMiddlewareFilter = null;
 
   const onPreComplete = (err) => {
     if (err != null) {
@@ -74,7 +77,15 @@ function QueryCursor(query) {
       this.listeners('error').length > 0 && this.emit('error', err);
       return;
     }
-    Object.assign(this.options, query._optionsForExec());
+    const { middleware, ...options } = query._optionsForExec();
+    Object.assign(this.options, options);
+    // `middleware` is a Mongoose-only option used to skip user hooks; strip it
+    // so it isn't passed through to the MongoDB driver. `this.options` is public
+    // and may be modified while pre hooks run, so check the target after assign.
+    if (Object.hasOwn(this.options, 'middleware')) {
+      delete this.options.middleware;
+    }
+    this._postMiddlewareFilter = buildMiddlewareFilter(query.options, 'post');
     this._transforms = this._transforms.concat(query._transforms.slice());
     if (this.options.transform) {
       this._transforms.push(this.options.transform);
@@ -98,7 +109,8 @@ function QueryCursor(query) {
     }
   };
 
-  model.hooks.execPre('find', query).then(() => onPreComplete(null), err => onPreComplete(err));
+  const preFilter = buildMiddlewareFilter(query.options, 'pre');
+  model.hooks.execPre('find', query, [], { filter: preFilter }).then(() => onPreComplete(null), err => onPreComplete(err));
 }
 
 util.inherits(QueryCursor, Readable);
@@ -607,7 +619,7 @@ function _populateBatch() {
 
 function _nextDoc(ctx, doc, pop, callback) {
   if (ctx.query._mongooseOptions.lean) {
-    return ctx.model.hooks.execPost('find', ctx.query, [[doc]]).then(() => callback(null, doc), err => callback(err));
+    return ctx.model.hooks.execPost('find', ctx.query, [[doc]], { filter: ctx._postMiddlewareFilter }).then(() => callback(null, doc), err => callback(err));
   }
 
   const { model, _fields, _userProvidedFields, options } = ctx.query;
@@ -618,7 +630,7 @@ function _nextDoc(ctx, doc, pop, callback) {
     if (options.session != null) {
       doc.$session(options.session);
     }
-    ctx.model.hooks.execPost('find', ctx.query, [[doc]]).then(() => callback(null, doc), err => callback(err));
+    ctx.model.hooks.execPost('find', ctx.query, [[doc]], { filter: ctx._postMiddlewareFilter }).then(() => callback(null, doc), err => callback(err));
   });
 }
 

package/lib/helpers/buildMiddlewareFilter.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const isPOJO = require('./isPOJO');
 const symbols = require('../schema/symbols');
 
 /**
@@ -15,10 +16,27 @@ const isBuiltInMiddleware = hook => hook.fn[symbols.builtInMiddleware];
  * @returns {Function|null} - null runs all middleware, isBuiltInMiddleware skips user middleware
  */
 function buildMiddlewareFilter(options, phase) {
-  const shouldRun = options?.middleware?.[phase] ?? options?.middleware ?? true;
-  return shouldRun ? null : isBuiltInMiddleware;
+  const shouldSkip = options?.middleware === false || options?.middleware?.[phase] === false;
+  return shouldSkip ? isBuiltInMiddleware : null;
+}
+
+/**
+ * kareem `getOptions` implementation for custom statics and methods: reads the
+ * `middleware` option from the call's last argument if it is a plain object.
+ *
+ * @param {Array} args - Arguments the custom static or method was called with
+ * @returns {object} - Per-call kareem options with pre/post filters
+ */
+function middlewareFiltersFromLastArg(args) {
+  const lastArg = args[args.length - 1];
+  const options = isPOJO(lastArg) ? lastArg : null;
+  return {
+    pre: { filter: buildMiddlewareFilter(options, 'pre') },
+    post: { filter: buildMiddlewareFilter(options, 'post') }
+  };
 }
 
 module.exports = {
-  buildMiddlewareFilter
+  buildMiddlewareFilter,
+  middlewareFiltersFromLastArg
 };

package/lib/helpers/model/applyHooks.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { buildMiddlewareFilter } = require('../buildMiddlewareFilter');
+const { buildMiddlewareFilter, middlewareFiltersFromLastArg } = require('../buildMiddlewareFilter');
 
 /*!
  * ignore
@@ -118,8 +118,15 @@ function applyHooks(model, schema, options) {
     }
     const originalMethod = objToDecorate[method];
     objToDecorate[`$__${method}`] = objToDecorate[method];
+    // Only read the `middleware` option from the method's last argument if
+    // the method opts in via `supportsMiddlewareOption`. Custom methods have
+    // arbitrary signatures, so the last argument may be an object with an
+    // unrelated `middleware` property.
+    const methodOptions = originalMethod.supportsMiddlewareOption === true ?
+      { ...customMethodOptions, getOptions: middlewareFiltersFromLastArg } :
+      customMethodOptions;
     objToDecorate[method] = middleware.
-      createWrapper(method, originalMethod, null, customMethodOptions);
+      createWrapper(method, originalMethod, null, methodOptions);
   }
 }
 

package/lib/helpers/model/applyStaticHooks.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const { middlewareFiltersFromLastArg } = require('../buildMiddlewareFilter');
 const { queryMiddlewareFunctions, aggregateMiddlewareFunctions, modelMiddlewareFunctions, documentMiddlewareFunctions } = require('../../constants');
 
 const middlewareFunctions = Array.from(
@@ -27,7 +28,14 @@ module.exports = function applyStaticHooks(model, hooks, statics) {
     if (hooks.hasHooks(key)) {
       const original = model[key];
 
-      model[key] = hooks.createWrapper(key, original);
+      // Only read the `middleware` option from the static's last argument if
+      // the static opts in via `supportsMiddlewareOption`. Custom statics have
+      // arbitrary signatures, so the last argument may be an object with an
+      // unrelated `middleware` property.
+      const wrapperOptions = original.supportsMiddlewareOption === true ?
+        { getOptions: middlewareFiltersFromLastArg } :
+        undefined;
+      model[key] = hooks.createWrapper(key, original, null, wrapperOptions);
     }
   }
 };

package/lib/model.js

@@ -1229,8 +1229,8 @@ Model.createCollection = async function createCollection(options) {
 
   // Remove middleware option before passing to MongoDB
   if (options?.middleware != null) {
-    options = { ...options };
-    delete options.middleware;
+    const { middleware, ...driverOptions } = options;
+    options = driverOptions;
   }
 
   [options] = await this.hooks.execPre('createCollection', this, [options], { filter: preFilter }).catch(err => {
@@ -2134,6 +2134,48 @@ Model.find = function find(conditions, projection, options) {
   return mq.find(conditions);
 };
 
+/**
+ * Finds documents and counts the number of documents matching the filter.
+ *
+ * This function fires both `find` and `countDocuments` middleware.
+ *
+ * #### Example:
+ *
+ *     const [adventures, total] = await Adventure.findAndCount(
+ *       { type: 'jungle' },
+ *       null,
+ *       { sort: { name: 1 }, skip: 10, limit: 10 }
+ *     );
+ *
+ *     adventures; // Array of at most 10 documents matching type 'jungle'
+ *     total; // Number of documents matching type 'jungle'
+ *
+ * @param {object|ObjectId} filter
+ * @param {object|string|string[]} [projection] optional fields to return
+ * @param {object} [options] optional query options
+ * @return {Promise<Array>} a promise that resolves to `[documents, total]`
+ * @api public
+ */
+
+Model.findAndCount = async function findAndCount(conditions, projection, options) {
+  _checkContext(this, 'findAndCount');
+
+  if (options == null) {
+    throw new MongooseError('Model.findAndCount() requires an `options` argument with `sort` and `limit`');
+  }
+  if (options.sort == null) {
+    throw new MongooseError('Model.findAndCount() requires `options.sort`');
+  }
+  if (options.limit == null) {
+    throw new MongooseError('Model.findAndCount() requires `options.limit`');
+  }
+
+  const findQuery = this.find(conditions, projection, options);
+  const countQuery = findQuery.clone().countDocuments().skip(0).limit(null);
+
+  return Promise.all([findQuery.exec(), countQuery.exec()]);
+};
+
 /**
  * Finds a single document by its _id field. `findById(id)` is equivalent to `findOne({ _id: id })`.
  *
@@ -4597,8 +4639,8 @@ async function _populatePath(model, docs, populateOptions) {
         select = select.filter(field => field !== '-_id');
       } else {
         // preserve original select conditions by copying
-        select = { ...select };
-        delete select._id;
+        const { _id, ...selectWithoutId } = select;
+        select = selectWithoutId;
       }
     }
 

package/lib/query.js

@@ -5329,7 +5329,8 @@ Query.prototype._applyPaths = function applyPaths() {
  * Returns a wrapper around a [mongodb driver cursor](https://mongodb.github.io/node-mongodb-native/7.0/classes/FindCursor.html).
  * A QueryCursor exposes a Streams3 interface, as well as a `.next()` function.
  *
- * The `.cursor()` function triggers pre find hooks, but **not** post find hooks.
+ * The `.cursor()` function triggers pre find hooks before opening the cursor
+ * and post find hooks once per document, with an array containing that document.
  *
  * #### Example:
  *
@@ -5358,9 +5359,14 @@ Query.prototype._applyPaths = function applyPaths() {
  * #### Valid options
  *
  *   - `transform`: optional function which accepts a mongoose document. The return value of the function will be emitted on `data` and returned by `.next()`.
+ *   - [`middleware`](https://mongoosejs.com/docs/middleware.html#skipping): set to `false` to skip all user-defined middleware, or `{ pre: false }` / `{ post: false }` to skip only pre or post find hooks
  *
  * @return {QueryCursor}
  * @param {object} [options]
+ * @param {Function} [options.transform] optional function which accepts a mongoose document. The return value of the function will be emitted on `data` and returned by `.next()`.
+ * @param {boolean|object} [options.middleware=true] set to `false` to skip all user-defined middleware
+ * @param {boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
+ * @param {boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @see QueryCursor https://mongoosejs.com/docs/api/querycursor.html
  * @api public
  */

package/lib/schema/array.js

@@ -400,7 +400,15 @@ SchemaArray.prototype.cast = function(value, doc, init, prev, options) {
           if (options.virtuals) {
             opts.virtuals = options.virtuals;
           }
-          rawValue[i] = caster.applySetters(rawValue[i], doc, init, void 0, opts);
+          if (rawValue[i] === undefined && caster.defaultValue !== undefined) {
+            // No need to add _skipMarkModified to opts here (fallback for `getDefault()` opts parameter)
+            // because array setters don't rely on Document.prototype.set() - subdocuments do rely on
+            // Document.prototype.set() when applying setters, which is why _skipMarkModified is necessary
+            // for subdocuments. But here we know that `caster` is an array not a subdocument.
+            rawValue[i] = caster.getDefault(doc, init, null, opts);
+          } else {
+            rawValue[i] = caster.applySetters(rawValue[i], doc, init, void 0, opts);
+          }
         }
       } catch (e) {
         // rethrow

package/lib/schema/documentArray.js

@@ -466,8 +466,8 @@ SchemaDocumentArray.prototype.cast = function(value, doc, init, prev, options) {
         // Don't pass `path` to $init - it's only for this DocumentArray itself, not its element fields.
         // Element subdocuments use relative paths internally for change tracking.
         if (options.path != null) {
-          options = { ...options };
-          delete options.path;
+          const { path, ...initOptions } = options;
+          options = initOptions;
         }
         rawArray[i] = subdoc.$init(rawArray[i], options);
       } else {

package/lib/schema/subdocument.js

@@ -206,8 +206,8 @@ SchemaSubdocument.prototype.cast = function(val, doc, init, priorVal, options) {
     // For change tracking, subdocuments use relative paths internally.
     // Here, `options.path` contains the absolute path and is only used by the subdocument constructor, not by $init.
     if (options.path != null) {
-      options = { ...options };
-      delete options.path;
+      const { path, ...initOptions } = options;
+      options = initOptions;
     }
     subdoc.$init(val, options);
     const exclude = isExclusive(selected);

package/lib/schema.js

@@ -2280,6 +2280,37 @@ Schema.prototype.plugin = function(fn, opts) {
   return this;
 };
 
+/**
+ * Adds a query helper to this schema. Equivalent to `schema.query[name] = fn`.
+ *
+ * #### Example:
+ *
+ *     schema.queryHelper('byName', function(name) {
+ *       return this.where({ name });
+ *     });
+ *     const Test = mongoose.model('Test', schema);
+ *     await Test.find().byName('John'); // Equivalent to `Test.find({ name: 'John' })`
+ *
+ * @param {string} name The query helper name.
+ * @param {Function} fn The query helper function.
+ * @return {Schema} this
+ * @api public
+ */
+
+Schema.prototype.queryHelper = function queryHelper(name, fn) {
+  if (typeof name !== 'string') {
+    throw new MongooseError('First param to `schema.queryHelper()` must be a string, ' +
+      'got "' + (typeof name) + '"');
+  }
+  if (typeof fn !== 'function') {
+    throw new MongooseError('Second param to `schema.queryHelper()` must be a function, ' +
+      'got "' + (typeof fn) + '"');
+  }
+
+  this.query[name] = fn;
+  return this;
+};
+
 /**
  * Adds an instance method to documents constructed from Models compiled from this schema.
  *
@@ -2310,9 +2341,21 @@ Schema.prototype.plugin = function(fn, opts) {
  *
  * NOTE: `Schema.method()` adds instance methods to the `Schema.methods` object. You can also add instance methods directly to the `Schema.methods` object as seen in the [guide](https://mongoosejs.com/docs/guide.html#methods)
  *
+ * If the method has hooks registered via `schema.pre('meow')` or `schema.post('meow')`, you can allow callers
+ * to skip them for a single call by setting `supportsMiddlewareOption = true` on the function:
+ *
+ *     schema.method('meow', function(options = {}) {
+ *       console.log('meeeeeoooooooooooow');
+ *     });
+ *     schema.methods.meow.supportsMiddlewareOption = true;
+ *
+ *     // Skips `pre('meow')` and `post('meow')` hooks
+ *     await fizz.meow({ middleware: false });
+ *
  * @param {string|object} name The Method Name for a single function, or an Object of "string-function" pairs.
  * @param {Function} [fn] The Function in a single-function definition.
  * @api public
+ * @see Skip Middleware https://mongoosejs.com/docs/middleware.html#skip-custom-statics-and-methods
  */
 
 Schema.prototype.method = function(name, fn, options) {
@@ -2355,10 +2398,22 @@ Schema.prototype.method = function(name, fn, options) {
  *
  * If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.
  *
+ * If the static has hooks registered via `schema.pre('findByName')` or `schema.post('findByName')`, you can allow
+ * callers to skip them for a single call by setting `supportsMiddlewareOption = true` on the function:
+ *
+ *     schema.static('findByName', function(name, options = {}) {
+ *       return this.find({ name: name });
+ *     });
+ *     schema.statics.findByName.supportsMiddlewareOption = true;
+ *
+ *     // Skips `pre('findByName')` and `post('findByName')` hooks
+ *     await Drink.findByName('LaCroix', { middleware: false });
+ *
  * @param {string|object} name The Method Name for a single function, or an Object of "string-function" pairs.
  * @param {Function} [fn] The Function in a single-function definition.
  * @api public
  * @see Statics https://mongoosejs.com/docs/guide.html#statics
+ * @see Skip Middleware https://mongoosejs.com/docs/middleware.html#skip-custom-statics-and-methods
  */
 
 Schema.prototype.static = function(name, fn) {

package/lib/schemaType.js

@@ -176,8 +176,7 @@ SchemaType.prototype.path;
  */
 
 SchemaType.prototype.toJSON = function toJSON() {
-  const res = { ...this };
-  delete res.parentSchema;
+  const { parentSchema, ...res } = this;
   return res;
 };
 
@@ -1299,11 +1298,12 @@ SchemaType.prototype.ref = function(ref) {
  * @param {object} options
  * @param {object} [options.context]
  * @param {boolean} [options.skipCast]
+ * @param {object} [applySettersOptions] passed to applySetters
  * @return {any} The Stored default value.
  * @api private
  */
 
-SchemaType.prototype.getDefault = function getDefault(parentDoc, init, options) {
+SchemaType.prototype.getDefault = function getDefault(parentDoc, init, options, applySettersOptions) {
   let ret;
   if (this.defaultValue == null) {
     return this.defaultValue;
@@ -1337,7 +1337,13 @@ SchemaType.prototype.getDefault = function getDefault(parentDoc, init, options)
       return this._applySetters(ret, parentDoc);
     }
 
-    const casted = this.applySetters(ret, parentDoc, init, undefined, setOptionsForDefaults);
+    const casted = this.applySetters(
+      ret,
+      parentDoc,
+      init,
+      undefined,
+      applySettersOptions ?? setOptionsForDefaults
+    );
     if (casted && !Array.isArray(casted) && casted.$isSingleNested) {
       casted.$__parent = parentDoc;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "9.9.5",
+  "version": "9.10.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -21,8 +21,8 @@
   "license": "MIT",
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "kareem": "3.3.0",
-    "mongodb": "~7.5",
+    "kareem": "3.4.0",
+    "mongodb": "~7.6",
     "mpath": "0.9.0",
     "mquery": "6.0.0",
     "ms": "2.1.3",
@@ -53,7 +53,7 @@
     "markdownlint-cli2": "0.23.2",
     "marked": "18.0.11",
     "mkdirp": "^3.0.1",
-    "mocha": "12.0.0-rc.5",
+    "mocha": "12.0.0-rc.6",
     "moment": "2.30.1",
     "mongodb-client-encryption": "^7.2.0",
     "mongodb-memory-server": "11.2.0",

package/types/aggregate.d.ts

@@ -10,6 +10,19 @@ declare module 'mongoose' {
     [key: string]: any;
   }
 
+  interface AggregateCursorMiddlewareOptions {
+    /** If `false`, skip pre aggregate middleware. Aggregate cursors do not run post aggregate middleware. */
+    pre?: boolean;
+    post?: never;
+  }
+
+  interface AggregateCursorOptions extends Omit<mongodb.AggregationCursorOptions & mongodb.Abortable, 'session'>, SessionOption {
+    middleware?: boolean | AggregateCursorMiddlewareOptions;
+    transform?: (doc: any) => any;
+    useMongooseAggCursor?: boolean;
+    [key: string]: unknown;
+  }
+
   class Aggregate<ResultType> implements SessionOperation {
     /**
      * Returns an asyncIterator for use with [`for/await/of` loops](https://thecodebarbarian.com/getting-started-with-async-iterators-in-node-js)
@@ -62,7 +75,7 @@ declare module 'mongoose' {
     /**
      * Sets the cursor option for the aggregation query
      */
-    cursor<DocType = any>(options?: Record<string, unknown>): Cursor<DocType>;
+    cursor<DocType = any>(options?: AggregateCursorOptions): Cursor<DocType>;
 
 
     /** Executes the aggregate pipeline on the currently bound Model. */

package/types/document.d.ts

@@ -96,7 +96,7 @@ declare module 'mongoose' {
 
     /** Returns the model with the given name on this document's associated connection. */
     $model<ModelType extends Model<unknown>>(name: string): ModelType;
-    $model<ModelType extends Model<DocType>>(): ModelType;
+    $model<ModelType extends Model<DocType, any, any, any>>(): ModelType;
 
     /**
      * A string containing the current operation that Mongoose is executing
@@ -232,7 +232,7 @@ declare module 'mongoose' {
 
     /** Returns the model with the given name on this document's associated connection. */
     model<ModelType extends Model<unknown>>(name: string): ModelType;
-    model<ModelType extends Model<DocType>>(): ModelType;
+    model<ModelType extends Model<DocType, any, any, any>>(): ModelType;
 
     /** Returns the list of paths that have been modified. */
     modifiedPaths(options?: { includeChildren?: boolean }): Array<string>;

package/types/index.d.ts

@@ -493,6 +493,24 @@ declare module 'mongoose' {
     method<Context = THydratedDocumentType>(name: string, fn: (this: Context, ...args: any[]) => any, opts?: any): this;
     method(obj: Partial<TInstanceMethods>): this;
 
+    /** Adds a query helper to this schema. */
+    queryHelper<Name extends string, Fn extends (this: QueryWithHelpers<any, DocType, TQueryHelpers, RawDocType>, ...args: any[]) => any>(
+      name: Name,
+      fn: Fn
+    ): Schema<
+      RawDocType,
+      TModelType,
+      TInstanceMethods,
+      TQueryHelpers & { [K in Name]: Fn },
+      TVirtuals,
+      TStaticMethods,
+      TSchemaOptions,
+      DocType,
+      THydratedDocumentType,
+      TSchemaDefinition,
+      LeanResultType
+    >;
+
     /** Object of currently defined methods on this schema. */
     methods: AddThisParameter<TInstanceMethods, THydratedDocumentType> & AnyObject;
 
@@ -667,12 +685,41 @@ declare module 'mongoose' {
 
     /** Adds static "class" methods to Models compiled from this schema. */
     static<K extends keyof TStaticMethods>(name: K, fn: TStaticMethods[K]): this;
-    static(obj: Partial<TStaticMethods> & { [name: string]: (this: TModelType, ...args: any[]) => any }): this;
-    static(name: string, fn: (this: TModelType, ...args: any[]) => any): this;
+    static<Fns extends Partial<TStaticMethods> & { [name: string]: (this: TModelType, ...args: any[]) => any }>(
+      obj: Fns
+    ): Schema<
+      RawDocType,
+      TModelType,
+      TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals,
+      TStaticMethods & Fns,
+      TSchemaOptions,
+      DocType,
+      THydratedDocumentType,
+      TSchemaDefinition,
+      LeanResultType
+    >;
+    static<Name extends string, Fn extends (this: TModelType, ...args: any[]) => any>(
+      name: Name,
+      fn: Fn
+    ): Schema<
+      RawDocType,
+      TModelType,
+      TInstanceMethods,
+      TQueryHelpers,
+      TVirtuals,
+      TStaticMethods & { [K in Name]: Fn },
+      TSchemaOptions,
+      DocType,
+      THydratedDocumentType,
+      TSchemaDefinition,
+      LeanResultType
+    >;
 
     /** Object of currently defined statics on this schema. */
     statics: { [F in keyof TStaticMethods]: TStaticMethods[F] } &
-    { [name: string]: (this: TModelType, ...args: any[]) => unknown };
+    { [name: string]: ((this: TModelType, ...args: any[]) => unknown) & SupportsMiddlewareOption };
 
     toJSONSchema(options?: { useBsonType?: boolean }): Record<string, any>;
 
@@ -825,6 +872,7 @@ declare module 'mongoose' {
   export type ReturnsNewDoc = { new: true } | { returnOriginal: false } | { returnDocument: 'after' };
 
   export type ArrayProjectionOperators = { $slice: number | [number, number]; $elemMatch?: never } | { $elemMatch: Record<string, any>; $slice?: never };
+  export type ProjectionOperators = { $meta: string };
   /**
    * This Type Assigns `Element | undefined` recursively to the `T` type.
    * if it is an array it will do this to the element of the array, if it is an object it will do this for the properties of the object.
@@ -842,14 +890,14 @@ declare module 'mongoose' {
     }
   */
   export type Projector<T, Element> = T extends Array<infer U>
-    ? Projector<U, Element> | ArrayProjectionOperators
+    ? Projector<U, Element> | ArrayProjectionOperators | ProjectionOperators
     : T extends TreatAsPrimitives
-      ? Element
+      ? Element | ProjectionOperators
       : T extends Record<string, any>
         ? {
-          [K in keyof T]?: T[K] extends Record<string, any> ? Projector<T[K], Element> | Element : Element;
+          [K in keyof T]?: T[K] extends Record<string, any> ? Projector<T[K], Element> | Element | ProjectionOperators : Element | ProjectionOperators;
         }
-        : Element;
+        : Element | ProjectionOperators;
   type _IDType = { _id?: boolean | number };
   export type InclusionProjection<T> = IsItRecordAndNotAny<T> extends true
     ? Omit<Projector<WithLevel1NestedPaths<T>, boolean | number>, '_id'> & _IDType
@@ -1181,7 +1229,7 @@ declare module 'mongoose' {
   /* for ts-mongoose */
   export class mquery { }
 
-  export function overwriteMiddlewareResult(val: any): Kareem.OverwriteMiddlewareResult;
+  export function overwriteMiddlewareResult(val: any): Kareem.OverwriteResult;
 
   export function skipMiddlewareFunction(val: any): Kareem.SkipWrappedFunction;
 

package/types/middlewares.d.ts

@@ -41,6 +41,15 @@ declare module 'mongoose' {
     post?: boolean;
   }
 
+  interface SupportsMiddlewareOption {
+    /**
+     * Set to `true` to let callers skip this custom static's or method's middleware
+     * by passing `{ middleware: false }` as the last argument.
+     * See [skipping middleware for custom statics and methods](https://mongoosejs.com/docs/middleware.html#skip-custom-statics-and-methods).
+     */
+    supportsMiddlewareOption?: boolean;
+  }
+
   type PreMiddlewareFunction<ThisType = any> = (
     this: ThisType,
     opts?: Record<string, any>
@@ -60,7 +69,7 @@ declare module 'mongoose' {
     this: ThisType,
     opts: SaveOptions
   ) => void | Promise<void> | Kareem.SkipWrappedFunction;
-  type PostMiddlewareFunction<ThisType = any, ResType = any> = (this: ThisType, res: ResType, next: CallbackWithoutResultAndOptionalError) => void | Promise<void> | Kareem.OverwriteMiddlewareResult;
+  type PostMiddlewareFunction<ThisType = any, ResType = any> = (this: ThisType, res: ResType, next: CallbackWithoutResultAndOptionalError) => void | Promise<void> | Kareem.OverwriteResult;
   type ErrorHandlingMiddlewareFunction<ThisType = any, ResType = any> = (this: ThisType, err: NativeError, res: ResType, next: CallbackWithoutResultAndOptionalError) => void;
-  type ErrorHandlingMiddlewareWithOption<ThisType = any, ResType = any> = (this: ThisType, err: NativeError, res: ResType | null, next: CallbackWithoutResultAndOptionalError) => void | Promise<void> | Kareem.OverwriteMiddlewareResult;
+  type ErrorHandlingMiddlewareWithOption<ThisType = any, ResType = any> = (this: ThisType, err: NativeError, res: ResType | null, next: CallbackWithoutResultAndOptionalError) => void | Promise<void> | Kareem.OverwriteResult;
 }

package/types/models.d.ts

@@ -445,6 +445,18 @@ declare module 'mongoose' {
      * equivalent to `findOne({ _id: id })`. If you want to query by a document's
      * `_id`, use `findById()` instead of `findOne()`.
      */
+    findById<const Projection extends ProjectionType<TRawDocType>>(
+      id: any,
+      projection: Projection,
+      options: QueryOptions<TRawDocType> & { lean: true }
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
     findById<ResultDoc = THydratedDocumentType>(
       id: any,
       projection: ProjectionType<TRawDocType> | null | undefined,
@@ -483,6 +495,54 @@ declare module 'mongoose' {
     >;
 
     /** Finds one document. */
+    findOne<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: Projection,
+      options?: QueryOptions<TRawDocType> & { lean?: false } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
+    findOne<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: undefined | null,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
+    findOne<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: Projection,
+      options: QueryOptions<TRawDocType> & { lean: true } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
+    findOne<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: undefined | null,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOne',
+      TInstanceMethods & TVirtuals
+    >;
     findOne<ResultDoc = THydratedDocumentType>(
       filter: QueryFilter<TRawDocType>,
       projection: ProjectionType<TRawDocType> | null | undefined,
@@ -780,6 +840,54 @@ declare module 'mongoose' {
     >;
 
     /** Creates a `find` query: gets a list of documents that match `filter`. */
+    find<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: Projection,
+      options?: QueryOptions<TRawDocType> & { lean?: false } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals>[],
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
+    find<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: undefined | null,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals>[],
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
+    find<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: Projection,
+      options: QueryOptions<TRawDocType> & { lean: true } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection>[],
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
+    find<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: undefined | null,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true } & mongodb.Abortable
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection>[],
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'find',
+      TInstanceMethods & TVirtuals
+    >;
     find<ResultDoc = THydratedDocumentType>(
       filter: QueryFilter<TRawDocType>,
       projection: ProjectionType<TRawDocType> | null | undefined,
@@ -841,7 +949,51 @@ declare module 'mongoose' {
       TInstanceMethods & TVirtuals
     >;
 
+    /** Finds documents and counts the number of documents matching `filter`. */
+    findAndCount<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      projection: Projection,
+      options: QueryOptions<TRawDocType> & { sort: any; limit: number; lean: true } & mongodb.Abortable
+    ): Promise<[ApplyProjection<TRawDocType, Projection>[], number]>;
+    findAndCount<ResultDoc = THydratedDocumentType>(
+      filter: QueryFilter<TRawDocType>,
+      projection: ProjectionType<TRawDocType> | null | undefined,
+      options: QueryOptions<TRawDocType> & { sort: any; limit: number; lean: true } & mongodb.Abortable
+    ): Promise<[GetLeanResultType<TRawDocType, TRawDocType[], 'find'>, number]>;
+    findAndCount<ResultDoc = THydratedDocumentType>(
+      filter: QueryFilter<TRawDocType>,
+      projection: ProjectionType<TRawDocType> | null | undefined,
+      options: QueryOptions<TRawDocType> & { sort: any; limit: number; lean: false } & mongodb.Abortable
+    ): Promise<[ResultDoc[], number]>;
+    findAndCount<ResultDoc = THydratedDocumentType>(
+      filter: QueryFilter<TRawDocType>,
+      projection: ProjectionType<TRawDocType> | null | undefined,
+      options: QueryOptions<TRawDocType> & { sort: any; limit: number } & mongodb.Abortable
+    ): Promise<[HasLeanOption<TSchema> extends true ? TLeanResultType[] : ResultDoc[], number]>;
+
     /** Creates a `findByIdAndDelete` query, filtering by the given `_id`. */
+    findByIdAndDelete<const Projection extends ProjectionType<TRawDocType>>(
+      id: mongodb.ObjectId | any,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
+    findByIdAndDelete<const Projection extends ProjectionType<TRawDocType>>(
+      id: mongodb.ObjectId | any,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ApplyProjection<TRawDocType, Projection>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
     findByIdAndDelete<ResultDoc = THydratedDocumentType>(
       id: mongodb.ObjectId | any,
       options: QueryOptions<TRawDocType> & { includeResultMetadata: true, lean: true }
@@ -900,6 +1052,30 @@ declare module 'mongoose' {
 
 
     /** Creates a `findOneAndUpdate` query, filtering by the given `_id`. */
+    findByIdAndUpdate<const Projection extends ProjectionType<TRawDocType>>(
+      id: mongodb.ObjectId | any,
+      update: UpdateQuery<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
+    findByIdAndUpdate<const Projection extends ProjectionType<TRawDocType>>(
+      id: mongodb.ObjectId | any,
+      update: UpdateQuery<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ApplyProjection<TRawDocType, Projection>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findByIdAndUpdate<ResultDoc = THydratedDocumentType>(
       filter: QueryFilter<TRawDocType>,
       update: UpdateQuery<TRawDocType>,
@@ -986,6 +1162,50 @@ declare module 'mongoose' {
     >;
 
     /** Creates a `findOneAndDelete` query: atomically finds the given document, deletes it, and returns the document as it was before deletion. */
+    findOneAndDelete<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndDelete<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndDelete<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndDelete<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ApplyProjection<TRawDocType, Projection>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndDelete',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndDelete<ResultDoc = THydratedDocumentType>(
       filter: QueryFilter<TRawDocType>,
       options: QueryOptions<TRawDocType> & { lean: true }
@@ -1076,6 +1296,54 @@ declare module 'mongoose' {
     >;
 
     /** Creates a `findOneAndReplace` query: atomically finds the given document and replaces it with `replacement`. */
+    findOneAndReplace<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      replacement: TRawDocType | AnyObject,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndReplace<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      replacement: TRawDocType | AnyObject,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndReplace<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      replacement: TRawDocType | AnyObject,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndReplace<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      replacement: TRawDocType | AnyObject,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ApplyProjection<TRawDocType, Projection>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndReplace',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndReplace<ResultDoc = THydratedDocumentType>(
       filter: QueryFilter<TRawDocType>,
       replacement: TRawDocType | AnyObject,
@@ -1198,6 +1466,54 @@ declare module 'mongoose' {
     >;
 
     /** Creates a `findOneAndUpdate` query: atomically find the first document that matches `filter` and apply `update`. */
+    findOneAndUpdate<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      update: UpdateQuery<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndUpdate<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      update: UpdateQuery<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean?: false; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ProjectedHydratedDocument<TRawDocType, Projection, TInstanceMethods, TQueryHelpers, TVirtuals>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndUpdate<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      update: UpdateQuery<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata?: false }
+    ): QueryWithHelpers<
+      ApplyProjection<TRawDocType, Projection> | null,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
+    findOneAndUpdate<const Projection extends ProjectionType<TRawDocType>>(
+      filter: QueryFilter<TRawDocType>,
+      update: UpdateQuery<TRawDocType>,
+      options: QueryOptions<TRawDocType> & { projection: Projection; lean: true; includeResultMetadata: true }
+    ): QueryWithHelpers<
+      ModifyResult<ApplyProjection<TRawDocType, Projection>>,
+      THydratedDocumentType,
+      TQueryHelpers,
+      TLeanResultType,
+      'findOneAndUpdate',
+      TInstanceMethods & TVirtuals
+    >;
     findOneAndUpdate<ResultDoc = THydratedDocumentType>(
       filter: QueryFilter<TRawDocType>,
       update: UpdateQuery<TRawDocType>,

package/types/utility.d.ts

@@ -1,4 +1,44 @@
 declare module 'mongoose' {
+  type IsNonDefiningProjection<Value, Key, Projection> = Value extends { $slice: any } | { $meta: any }
+    ? true
+    : Key extends '_id'
+      ? Value extends 0 | false
+        ? false
+        // Including `_id` only defines inclusion when it is the sole projected field.
+        : Exclude<keyof Projection, '_id'> extends never ? false : true
+      : false;
+  type ProjectionPath<Key> = Key extends `${infer Parent}.$` ? Parent : Key;
+  type DefiningProjectionKeys<Projection> = {
+    [Key in keyof Projection]-?: Key extends string
+      ? IsNonDefiningProjection<Projection[Key], Key, Projection> extends true ? never : ProjectionPath<Key>
+      : never
+  }[keyof Projection];
+  type DefiningProjectionValues<Projection> = {
+    [Key in keyof Projection]-?: IsNonDefiningProjection<Projection[Key], Key, Projection> extends true ? never : Projection[Key]
+  }[keyof Projection];
+
+  export type ApplyProjection<T, Projection> = Projection extends string
+    ? T
+    : Projection extends AnyObject
+      ? [DefiningProjectionKeys<Projection>] extends [never]
+        ? T
+        : Exclude<DefiningProjectionValues<Projection>, 0 | false | undefined> extends never
+          ? Omit<T, Extract<DefiningProjectionKeys<Projection>, keyof T>>
+          : Pick<T, Extract<DefiningProjectionKeys<Projection>, keyof T>> &
+            (Projection extends { _id?: infer Id }
+              ? Id extends 0 | false
+                ? unknown
+                : Pick<T, Extract<'_id', keyof T>>
+              : Pick<T, Extract<'_id', keyof T>>)
+      : T;
+
+  export type ProjectedHydratedDocument<RawDocType, Projection, TInstanceMethods = {}, TQueryHelpers = {}, TVirtuals = {}> =
+    Projection extends { _id?: infer Id }
+      ? Id extends 0 | false
+        ? Omit<HydratedDocument<ApplyProjection<RawDocType, Projection>, TInstanceMethods, TQueryHelpers, TVirtuals>, '_id'>
+        : HydratedDocument<ApplyProjection<RawDocType, Projection>, TInstanceMethods, TQueryHelpers, TVirtuals>
+      : HydratedDocument<ApplyProjection<RawDocType, Projection>, TInstanceMethods, TQueryHelpers, TVirtuals>;
+
   type IfAny<IFTYPE, THENTYPE, ELSETYPE = IFTYPE> = 0 extends 1 & IFTYPE
     ? THENTYPE
     : ELSETYPE;