mongoose 9.3.0 → 9.3.2

package/README.md

@@ -11,7 +11,7 @@ Mongoose is a [MongoDB](https://www.mongodb.org/) object modeling tool designed
 
 ## Documentation
 
-The official documentation website is [mongoosejs.com](http://mongoosejs.com/).
+The official documentation website is [mongoosejs.com](https://mongoosejs.com/).
 
 Mongoose 9.0.0 was released on November 21, 2025. You can find more details on [backwards breaking changes in 9.0.0 on our docs site](https://mongoosejs.com/docs/migrating_to_9.html).
 
@@ -25,7 +25,7 @@ Mongoose 9.0.0 was released on November 21, 2025. You can find more details on [
 
 ## Plugins
 
-Check out the [plugins search site](http://plugins.mongoosejs.io/) to see hundreds of related modules from the community. Next, learn how to write your own plugin from the [docs](http://mongoosejs.com/docs/plugins.html) or [this blog post](http://thecodebarbarian.com/2015/03/06/guide-to-mongoose-plugins).
+Check out the [plugins search site](https://plugins.mongoosejs.io/) to see hundreds of related modules from the community. Next, learn how to write your own plugin from the [docs](https://mongoosejs.com/docs/plugins.html) or [this blog post](http://thecodebarbarian.com/2015/03/06/guide-to-mongoose-plugins).
 
 ## Contributors
 
@@ -40,9 +40,7 @@ View all 400+ [contributors](https://github.com/Automattic/mongoose/graphs/contr
 
 ## Installation
 
-First install [Node.js](http://nodejs.org/) and [MongoDB](https://www.mongodb.org/downloads). Then:
-
-Then install the `mongoose` package using your preferred package manager:
+First install [Node.js](https://nodejs.org/) and [MongoDB](https://www.mongodb.org/downloads), then install the `mongoose` package using your preferred package manager:
 
 ### Using npm
 
@@ -140,16 +138,16 @@ const BlogPost = new Schema({
 
 Aside from defining the structure of your documents and the types of data you're storing, a Schema handles the definition of:
 
-* [Validators](http://mongoosejs.com/docs/validation.html) (async and sync)
-* [Defaults](http://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-default)
-* [Getters](http://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-get)
-* [Setters](http://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-set)
-* [Indexes](http://mongoosejs.com/docs/guide.html#indexes)
-* [Middleware](http://mongoosejs.com/docs/middleware.html)
-* [Methods](http://mongoosejs.com/docs/guide.html#methods) definition
-* [Statics](http://mongoosejs.com/docs/guide.html#statics) definition
-* [Plugins](http://mongoosejs.com/docs/plugins.html)
-* [pseudo-JOINs](http://mongoosejs.com/docs/populate.html)
+* [Validators](https://mongoosejs.com/docs/validation.html) (async and sync)
+* [Defaults](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-default)
+* [Getters](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-get)
+* [Setters](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-set)
+* [Indexes](https://mongoosejs.com/docs/guide.html#indexes)
+* [Middleware](https://mongoosejs.com/docs/middleware.html)
+* [Methods](https://mongoosejs.com/docs/guide.html#methods) definition
+* [Statics](https://mongoosejs.com/docs/guide.html#statics) definition
+* [Plugins](https://mongoosejs.com/docs/plugins.html)
+* [pseudo-JOINs](https://mongoosejs.com/docs/populate.html)
 
 The following example shows some of these features:
 
@@ -219,7 +217,7 @@ const instance = await MyModel.findOne({ /* ... */ });
 console.log(instance.my.key); // 'hello'
 ```
 
-For more details check out [the docs](http://mongoosejs.com/docs/queries.html).
+For more details check out [the docs](https://mongoosejs.com/docs/queries.html).
 
 **Important!** If you opened a separate connection using `mongoose.createConnection()` but attempt to access the model through `mongoose.model('ModelName')` it will not work as expected since it is not hooked up to an active db connection. In this case access your model through the connection you created:
 
@@ -274,7 +272,7 @@ Embedded documents enjoy all the same features as your models. Defaults, validat
 
 ### Middleware
 
-See the [docs](http://mongoosejs.com/docs/middleware.html) page.
+See the [docs](https://mongoosejs.com/docs/middleware.html) page.
 
 #### Intercepting and mutating method arguments
 
@@ -347,7 +345,7 @@ return a cursor.
 
 ## API Docs
 
-[Mongoose API documentation](http://mongoosejs.com/docs/api/mongoose.html), generated using [dox](https://github.com/tj/dox)
+[Mongoose API documentation](https://mongoosejs.com/docs/api/mongoose.html), generated using [dox](https://github.com/tj/dox)
 and [acquit](https://github.com/vkarpov15/acquit).
 
 ## Related Projects

package/lib/aggregate.js

@@ -170,7 +170,7 @@ Aggregate.prototype.append = function() {
     : [...arguments];
 
   if (!args.every(isOperator)) {
-    throw new Error('Arguments must be aggregate pipeline operators');
+    throw new MongooseError('Arguments must be aggregate pipeline operators');
   }
 
   this._pipeline = this._pipeline.concat(args);
@@ -203,7 +203,7 @@ Aggregate.prototype.append = function() {
  */
 Aggregate.prototype.addFields = function(arg) {
   if (typeof arg !== 'object' || arg === null || Array.isArray(arg)) {
-    throw new Error('Invalid addFields() argument. Must be an object');
+    throw new MongooseError('Invalid addFields() argument. Must be an object');
   }
   return this.append({ $addFields: Object.assign({}, arg) });
 };
@@ -259,7 +259,7 @@ Aggregate.prototype.project = function(arg) {
       fields[field] = include;
     });
   } else {
-    throw new Error('Invalid project() argument. Must be string or object');
+    throw new MongooseError('Invalid project() argument. Must be string or object');
   }
 
   return this.append({ $project: fields });
@@ -462,7 +462,7 @@ Aggregate.prototype.unwind = function() {
         $unwind: (arg[0] === '$') ? arg : '$' + arg
       });
     } else {
-      throw new Error('Invalid arg "' + arg + '" to unwind(), ' +
+      throw new MongooseError('Invalid arg "' + arg + '" to unwind(), ' +
         'must be string or object');
     }
   }
@@ -761,7 +761,7 @@ Aggregate.prototype.redact = function(expression, thenExpr, elseExpr) {
   if (arguments.length === 3) {
     if ((typeof thenExpr === 'string' && !validRedactStringValues.has(thenExpr)) ||
       (typeof elseExpr === 'string' && !validRedactStringValues.has(elseExpr))) {
-      throw new Error('If thenExpr or elseExpr is string, it must be either $$DESCEND, $$PRUNE or $$KEEP');
+      throw new MongooseError('If thenExpr or elseExpr is string, it must be either $$DESCEND, $$PRUNE or $$KEEP');
     }
 
     expression = {
@@ -796,7 +796,7 @@ Aggregate.prototype.explain = async function explain(verbosity) {
   const model = this._model;
 
   if (!this._pipeline.length) {
-    throw new Error('Aggregate has empty pipeline');
+    throw new MongooseError('Aggregate has empty pipeline');
   }
 
   prepareDiscriminatorPipeline(this._pipeline, this._model.schema);
@@ -1058,7 +1058,7 @@ Aggregate.prototype.pipelineForUnionWith = function pipelineForUnionWith() {
 
 Aggregate.prototype.exec = async function exec() {
   if (!this._model && !this._connection) {
-    throw new Error('Aggregate not bound to any Model');
+    throw new MongooseError('Aggregate not bound to any Model');
   }
   if (typeof arguments[0] === 'function') {
     throw new MongooseError('Aggregate.prototype.exec() no longer accepts a callback');

package/lib/cast/number.js

@@ -1,7 +1,5 @@
 'use strict';
 
-const assert = require('assert');
-
 /**
  * Given a value, cast it to a number, or throw an `Error` if the value
  * cannot be casted. `null` and `undefined` are considered valid.
@@ -24,7 +22,9 @@ module.exports = function castNumber(val) {
     val = Number(val);
   }
 
-  assert.ok(!isNaN(val));
+  if (isNaN(val)) {
+    throw new Error('Cast to Number failed: value is not a valid number');
+  }
   if (val instanceof Number) {
     return val.valueOf();
   }
@@ -38,5 +38,5 @@ module.exports = function castNumber(val) {
     return Number(val);
   }
 
-  assert.ok(false);
+  throw new Error('Cast to Number failed: value is not a valid number');
 };

package/lib/cast.js

@@ -35,7 +35,7 @@ const ALLOWED_GEOWITHIN_GEOJSON_TYPES = ['Polygon', 'MultiPolygon'];
  */
 module.exports = function cast(schema, obj, options, context) {
   if (Array.isArray(obj)) {
-    throw new Error('Query filter must be an object, got an array ', util.inspect(obj));
+    throw new Error('Query filter must be an object, got an array ' + util.inspect(obj));
   }
 
   if (obj == null) {

package/lib/connection.js

@@ -132,7 +132,7 @@ Object.defineProperty(Connection.prototype, 'readyState', {
   },
   set: function(val) {
     if (!(val in STATES)) {
-      throw new Error('Invalid connection state: ' + val);
+      throw new MongooseError('Invalid connection state: ' + val);
     }
 
     if (this._readyState !== val) {
@@ -655,7 +655,7 @@ Connection.prototype.createCollections = async function createCollections(option
 
 Connection.prototype.withSession = async function withSession(executor) {
   if (arguments.length === 0) {
-    throw new Error('Please provide an executor function');
+    throw new MongooseError('Please provide an executor function');
   }
   return await this.client.withSession(executor);
 };
@@ -713,7 +713,7 @@ Connection.prototype.startSession = async function startSession(options) {
  *       doc.isNew; // false
  *
  *       // Throw an error to abort the transaction
- *       throw new Error('Oops!');
+ *       throw new MongooseError('Oops!');
  *     },{ readPreference: 'primary' }).catch(() => {});
  *
  *     // true, `transaction()` reset the document's state because the
@@ -1310,7 +1310,7 @@ Connection.prototype._close = async function _close(force, destroy) {
  */
 
 Connection.prototype.doClose = function doClose() {
-  throw new Error('Connection#doClose unimplemented by driver');
+  throw new MongooseError('Connection#doClose unimplemented by driver');
 };
 
 /**
@@ -1453,7 +1453,7 @@ Connection.prototype.model = function model(name, schema, collection, options) {
     }
   }
   if (schema && !schema.instanceOfSchema) {
-    throw new Error('The 2nd parameter to `mongoose.model()` should be a ' +
+    throw new MongooseError('The 2nd parameter to `mongoose.model()` should be a ' +
       'schema or a POJO');
   }
 
@@ -1566,7 +1566,7 @@ Connection.prototype.deleteModel = function deleteModel(name) {
       }
     }
   } else {
-    throw new Error('First parameter to `deleteModel()` must be a string ' +
+    throw new MongooseError('First parameter to `deleteModel()` must be a string ' +
       'or regexp, got "' + name + '"');
   }
 

package/lib/cursor/queryCursor.js

@@ -132,7 +132,7 @@ QueryCursor.prototype._read = function() {
     }
     if (!doc) {
       this.push(null);
-      this.cursor.close(function(error) {
+      this.cursor.close((error) => {
         if (error) {
           return this.emit('error', error);
         }

package/lib/helpers/get.js

@@ -47,7 +47,7 @@ module.exports = function get(obj, path, def) {
     cur = getProperty(cur, part);
 
     if (!isPathArray) {
-      rest = rest.substr(part.length + 1);
+      rest = rest.substring(part.length + 1);
     }
   }
 

package/lib/helpers/projection/parseProjection.js

@@ -1,8 +1,13 @@
 'use strict';
 
 /**
- * Convert a string or array into a projection object, retaining all
- * `-` and `+` paths.
+ * Convert a string or array into a projection object. Treats `-foo` as
+ * equivalent to `foo: 0` depending on `retainMinusPaths`. If `retainMinusPaths`
+ * is true, then `-foo` will be included in the projection as `'-foo': 0`.
+ *
+ * @param {object|string|string[]} v
+ * @param {boolean} [retainMinusPaths]
+ * @return {object}
  */
 
 module.exports = function parseProjection(v, retainMinusPaths) {
@@ -22,9 +27,9 @@ module.exports = function parseProjection(v, retainMinusPaths) {
     if (!field) {
       continue;
     }
-    const include = '-' == field[0] ? 0 : 1;
+    const include = field.charAt(0) === '-' ? 0 : 1;
     if (!retainMinusPaths && include === 0) {
-      field = field.substring(1);
+      field = field.slice(1);
     }
     ret[field] = include;
   }

package/lib/model.js

@@ -61,6 +61,7 @@ const decorateDiscriminatorIndexOptions = require('./helpers/indexes/decorateDis
 const isPathSelectedInclusive = require('./helpers/projection/isPathSelectedInclusive');
 const leanPopulateMap = require('./helpers/populate/leanPopulateMap');
 const parallelLimit = require('./helpers/parallelLimit');
+const parseProjection = require('./helpers/projection/parseProjection');
 const prepareDiscriminatorPipeline = require('./helpers/aggregate/prepareDiscriminatorPipeline');
 const pushNestedArrayPaths = require('./helpers/model/pushNestedArrayPaths');
 const removeDeselectedForeignField = require('./helpers/populate/removeDeselectedForeignField');
@@ -189,7 +190,7 @@ Model.prototype.db;
 
 Model.useConnection = function useConnection(connection) {
   if (!connection) {
-    throw new Error('Please provide a connection.');
+    throw new MongooseError('Please provide a connection.');
   }
   if (this.db) {
     delete this.db.models[this.modelName];
@@ -824,7 +825,7 @@ Model.prototype.deleteOne = function deleteOne(options) {
     // `self` is passed to pre hooks as argument for backwards compatibility, but that
     // isn't the actual arguments passed to the wrapped function.
     if (res[0] !== self || res[1] !== options) {
-      throw new Error('Document deleteOne pre hooks cannot overwrite arguments');
+      throw new MongooseError('Document deleteOne pre hooks cannot overwrite arguments');
     }
     query.deleteOne(where, options);
     // Apply custom where conditions _after_ document deleteOne middleware for
@@ -3458,7 +3459,7 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
       sort((v1, v2) => v1.index - v2.index).
       map(v => v.error);
 
-    const validOps = validOpIndexes.sort().map(index => ops[index]);
+    const validOps = validOpIndexes.sort((a, b) => a - b).map(index => ops[index]);
 
     if (validOps.length === 0) {
       if (options.throwOnValidationError && validationErrors.length) {
@@ -3609,7 +3610,7 @@ async function buildPreSavePromise(document, options) {
   const preFilter = buildMiddlewareFilter(options, 'pre');
   const [newOptions] = await document.schema.s.hooks.execPre('save', document, [options], { filter: preFilter });
   if (newOptions !== options) {
-    throw new Error('Cannot overwrite options in pre("save") hook on bulkSave()');
+    throw new MongooseError('Cannot overwrite options in pre("save") hook on bulkSave()');
   }
 }
 
@@ -3849,7 +3850,7 @@ Model.castObject = function castObject(obj, options) {
 
 Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, options) {
   if (!Array.isArray(documents)) {
-    throw new Error(`bulkSave expects an array of documents to be passed, received \`${documents}\` instead`);
+    throw new MongooseError(`bulkSave expects an array of documents to be passed, received \`${documents}\` instead`);
   }
 
   setDefaultOptions();
@@ -3857,7 +3858,7 @@ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, op
   const writeOperations = documents.map((document, i) => {
     if (!options.skipValidation) {
       if (!(document instanceof Document)) {
-        throw new Error(`documents.${i} was not a mongoose document, documents must be an array of mongoose documents (instanceof mongoose.Document).`);
+        throw new MongooseError(`documents.${i} was not a mongoose document, documents must be an array of mongoose documents (instanceof mongoose.Document).`);
       }
       if (options.validateBeforeSave == null || options.validateBeforeSave) {
         const err = document.validateSync();
@@ -3935,7 +3936,7 @@ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, op
  * @api public
  */
 
-Model.hydrate = function(obj, projection, options) {
+Model.hydrate = function hydrate(obj, projection, options) {
   _checkContext(this, 'hydrate');
 
   if (options?.virtuals && options?.hydratedPopulatedDocs === false) {
@@ -3946,6 +3947,7 @@ Model.hydrate = function(obj, projection, options) {
     if (obj?.$__ != null) {
       obj = obj.toObject(internalToObjectOptions);
     }
+    projection = parseProjection(projection);
     obj = applyProjection(obj, projection);
   }
   const document = require('./queryHelpers').createModel(this, obj, projection, projection, options);
@@ -4947,7 +4949,7 @@ Model.compile = function compile(name, schema, collectionName, connection, base)
 Model.clientEncryption = function clientEncryption() {
   const ClientEncryption = this.base.driver.get().ClientEncryption;
   if (!ClientEncryption) {
-    throw new Error('The mongodb driver must be used to obtain a ClientEncryption object.');
+    throw new MongooseError('The mongodb driver must be used to obtain a ClientEncryption object.');
   }
 
   const client = this.collection?.conn?.client;

package/lib/mongoose.js

@@ -256,6 +256,12 @@ Mongoose.prototype.setDriver = function setDriver(driver) {
 Mongoose.prototype.set = function getsetOptions(key, value) {
   const _mongoose = this instanceof Mongoose ? this : mongoose;
 
+  if (key == null) {
+    const error = new SetOptionError();
+    error.addError(String(key), new SetOptionError.SetOptionInnerError(String(key)));
+    throw error;
+  }
+
   if (arguments.length === 1 && typeof key !== 'object') {
     if (VALID_OPTIONS.indexOf(key) === -1) {
       const error = new SetOptionError();

package/lib/query.js

@@ -185,7 +185,7 @@ function isEmptyFilter(obj) {
 // Helper function to check for empty/invalid filter
 function checkRequireFilter(filter, options) {
   if (options?.requireFilter && isEmptyFilter(filter)) {
-    throw new Error('Empty or invalid filter not allowed with requireFilter enabled');
+    throw new MongooseError('Empty or invalid filter not allowed with requireFilter enabled');
   }
 }
 
@@ -1113,7 +1113,7 @@ Query.prototype.select = function select() {
   if (!arg) return this;
 
   if (arguments.length !== 1) {
-    throw new Error('Invalid select: select only takes 1 argument');
+    throw new MongooseError('Invalid select: select only takes 1 argument');
   }
 
   this._validate('select');
@@ -1721,7 +1721,7 @@ Query.prototype.setOptions = function(options, overwrite) {
     return this;
   }
   if (typeof options !== 'object') {
-    throw new Error('Options must be an object, got "' + options + '"');
+    throw new MongooseError('Options must be an object, got "' + options + '"');
   }
 
   options = Object.assign({}, options);
@@ -3080,10 +3080,10 @@ Query.prototype.distinct = function(field, conditions, options) {
 
 Query.prototype.sort = function(arg, options) {
   if (arguments.length > 2) {
-    throw new Error('sort() takes at most 2 arguments');
+    throw new MongooseError('sort() takes at most 2 arguments');
   }
   if (options != null && typeof options !== 'object') {
-    throw new Error('sort() options argument must be an object or nullish');
+    throw new MongooseError('sort() options argument must be an object or nullish');
   }
 
   if (this.options.sort == null) {
@@ -4695,7 +4695,7 @@ Query.prototype.exec = async function exec(op) {
   }
 
   if (this.options?.sort && typeof this.options.sort === 'object' && Object.hasOwn(this.options.sort, '')) {
-    throw new Error('Invalid field "" passed to sort()');
+    throw new MongooseError('Invalid field "" passed to sort()');
   }
 
   if (this._execCount > 0) {

package/lib/schema.js

@@ -205,7 +205,7 @@ function aliasFields(schema, paths) {
     if (Array.isArray(alias)) {
       for (const a of alias) {
         if (typeof a !== 'string') {
-          throw new Error('Invalid value for alias option on ' + prop + ', got ' + a);
+          throw new MongooseError('Invalid value for alias option on ' + prop + ', got ' + a);
         }
 
         schema.aliases[a] = prop;
@@ -231,7 +231,7 @@ function aliasFields(schema, paths) {
     }
 
     if (typeof alias !== 'string') {
-      throw new Error('Invalid value for alias option on ' + prop + ', got ' + alias);
+      throw new MongooseError('Invalid value for alias option on ' + prop + ', got ' + alias);
     }
 
     schema.aliases[alias] = prop;
@@ -750,7 +750,7 @@ Schema.prototype.encryptionType = function encryptionType(encryptionType) {
     return this.options.encryptionType;
   }
   if (!(typeof encryptionType === 'string' || encryptionType === null)) {
-    throw new Error('invalid `encryptionType`: ${encryptionType}');
+    throw new MongooseError('invalid `encryptionType`: ${encryptionType}');
   }
   this.options.encryptionType = encryptionType;
 };
@@ -909,7 +909,7 @@ Schema.prototype.add = function add(obj, prefix) {
     if (val.instanceOfSchema && val.encryptionType() != null) {
       // schema.add({ field: <instance of encrypted schema> })
       if (this.encryptionType() != val.encryptionType()) {
-        throw new Error('encryptionType of a nested schema must match the encryption type of the parent schema.');
+        throw new MongooseError('encryptionType of a nested schema must match the encryption type of the parent schema.');
       }
 
       for (const [encryptedField, encryptedFieldConfig] of Object.entries(val.encryptedFields)) {
@@ -921,7 +921,7 @@ Schema.prototype.add = function add(obj, prefix) {
       const { encrypt } = val;
 
       if (this.encryptionType() == null) {
-        throw new Error('encryptionType must be provided');
+        throw new MongooseError('encryptionType must be provided');
       }
 
       this._addEncryptedField(fullPath, encrypt);
@@ -948,7 +948,7 @@ Schema.prototype.add = function add(obj, prefix) {
 Schema.prototype._addEncryptedField = function _addEncryptedField(path, fieldConfig) {
   const type = this.path(path).autoEncryptionType();
   if (type == null) {
-    throw new Error(`Invalid BSON type for FLE field: '${path}'`);
+    throw new MongooseError(`Invalid BSON type for FLE field: '${path}'`);
   }
 
   this.encryptedFields[path] = clone(fieldConfig);
@@ -1113,11 +1113,11 @@ Schema.prototype.alias = function alias(path, alias) {
 
 Schema.prototype.removeIndex = function removeIndex(index) {
   if (arguments.length > 1) {
-    throw new Error('removeIndex() takes only 1 argument');
+    throw new MongooseError('removeIndex() takes only 1 argument');
   }
 
   if (typeof index !== 'object' && typeof index !== 'string') {
-    throw new Error('removeIndex() may only take either an object or a string as an argument');
+    throw new MongooseError('removeIndex() may only take either an object or a string as an argument');
   }
 
   if (typeof index === 'object') {
@@ -1318,7 +1318,7 @@ Schema.prototype.path = function(path, obj) {
 
   for (const sub of subpaths) {
     if (utils.specialProperties.has(sub)) {
-      throw new Error('Cannot set special property `' + sub + '` on a schema');
+      throw new MongooseError('Cannot set special property `' + sub + '` on a schema');
     }
     fullPath = fullPath += (fullPath.length > 0 ? '.' : '') + sub;
     if (!branch[sub]) {
@@ -1331,7 +1331,7 @@ Schema.prototype.path = function(path, obj) {
           + fullPath
           + '` already set to type ' + branch[sub].name
           + '.';
-      throw new Error(msg);
+      throw new MongooseError(msg);
     }
     branch = branch[sub];
   }
@@ -2205,7 +2205,7 @@ Schema.prototype.post = function(name) {
 
 Schema.prototype.plugin = function(fn, opts) {
   if (typeof fn !== 'function') {
-    throw new Error('First param to `schema.plugin()` must be a function, ' +
+    throw new MongooseError('First param to `schema.plugin()` must be a function, ' +
       'got "' + (typeof fn) + '"');
   }
 
@@ -2480,7 +2480,7 @@ Object.defineProperty(Schema, 'indexTypes', {
     return indexTypes;
   },
   set: function() {
-    throw new Error('Cannot overwrite Schema.indexTypes');
+    throw new MongooseError('Cannot overwrite Schema.indexTypes');
   }
 });
 
@@ -2542,11 +2542,11 @@ Schema.prototype.virtual = function(name, options) {
 
   if (utils.hasUserDefinedProperty(options, ['ref', 'refPath'])) {
     if (options.localField == null) {
-      throw new Error('Reference virtuals require `localField` option');
+      throw new MongooseError('Reference virtuals require `localField` option');
     }
 
     if (options.foreignField == null) {
-      throw new Error('Reference virtuals require `foreignField` option');
+      throw new MongooseError('Reference virtuals require `foreignField` option');
     }
 
     const virtual = this.virtual(name);
@@ -2642,7 +2642,7 @@ Schema.prototype.virtual = function(name, options) {
   const parts = name.split('.');
 
   if (this.pathType(name) === 'real') {
-    throw new Error('Virtual path "' + name + '"' +
+    throw new MongooseError('Virtual path "' + name + '"' +
       ' conflicts with a real path in the schema');
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "9.3.0",
+  "version": "9.3.2",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",

package/types/index.d.ts

@@ -379,7 +379,12 @@ declare module 'mongoose' {
       >,
       TMethods = TSchemaOptions extends { methods: infer M } ? { [K in keyof M]: OmitThisParameter<M[K]> } : {},
       TStatics = TSchemaOptions extends { statics: infer S } ? { [K in keyof S]: OmitThisParameter<S[K]> } : {}
-    >(def: TSchemaDefinition, options: TSchemaOptions): Schema<
+    >(def: TSchemaDefinition, options: TSchemaOptions & {
+      statics?: SchemaOptionsStaticsPropertyType<
+        TStatics,
+        Model<RawDocType>
+      >
+    }): Schema<
       RawDocType,
       Model<RawDocType, any, any, any>,
       TMethods,
@@ -497,6 +502,7 @@ declare module 'mongoose' {
 
     /** Registers a plugin for this schema. */
     plugin<PFunc extends PluginFunction<DocType, TModelType, any, any, any, any>, POptions extends Parameters<PFunc>[1] = Parameters<PFunc>[1]>(fn: PFunc, opts?: POptions): this;
+    plugin<PFunc extends PluginFunction<DocType, Model<DocType, any, any, any, any, any>, any, any, any, any>, POptions extends Parameters<PFunc>[1] = Parameters<PFunc>[1]>(fn: PFunc, opts?: POptions): this;
 
     /** Defines a post hook for the model. */
 

package/types/schemaoptions.d.ts

@@ -7,6 +7,13 @@ declare module 'mongoose' {
     currentTime?: () => (NativeDate | number);
   }
 
+  type SchemaOptionsStaticsPropertyType<TStaticMethods, TModelType> = IfEquals<
+    TStaticMethods,
+    {},
+    Record<string, (...args: any[]) => unknown> & ThisType<TModelType>,
+    { [K in keyof TStaticMethods]: OmitThisParameter<TStaticMethods[K]> } & ThisType<TModelType>
+  >;
+
   type TypeKeyBaseType = string;
 
   type DefaultTypeKey = 'type';
@@ -222,12 +229,7 @@ declare module 'mongoose' {
     /**
      * Model Statics methods.
      */
-    statics?: IfEquals<
-      TStaticMethods,
-      {},
-      { [name: string]: (this: TModelType, ...args: any[]) => unknown },
-      AddThisParameter<TStaticMethods, TModelType>
-    >
+    statics?: SchemaOptionsStaticsPropertyType<TStaticMethods, TModelType>
 
     /**
      * Document instance methods.