mongoose 9.3.1 → 9.3.3

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

@@ -159,7 +159,7 @@ Aggregate.prototype.model = function(model) {
  *     const pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
  *     aggregate.append(pipeline);
  *
- * @param {...object|object[]} ops operator(s) to append. Can either be a spread of objects or a single parameter of a object array.
+ * @param {...object|object[]} ops operator(s) to append. Can either be a spread of objects or a single parameter of an object array.
  * @return {Aggregate}
  * @api public
  */

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) {
@@ -177,7 +177,7 @@ Connection.prototype.get = function getOption(key) {
  * Supported options include:
  *
  * - `maxTimeMS`: Set [`maxTimeMS`](https://mongoosejs.com/docs/api/query.html#Query.prototype.maxTimeMS()) for all queries on this connection.
- * - 'debug': If `true`, prints the operations mongoose sends to MongoDB to the console. If a writable stream is passed, it will log to that stream, without colorization. If a callback function is passed, it will receive the collection name, the method name, then all arugments passed to the method. For example, if you wanted to replicate the default logging, you could output from the callback `Mongoose: ${collectionName}.${methodName}(${methodArgs.join(', ')})`.
+ * - 'debug': If `true`, prints the operations mongoose sends to MongoDB to the console. If a writable stream is passed, it will log to that stream, without colorization. If a callback function is passed, it will receive the collection name, the method name, then all arguments passed to the method. For example, if you wanted to replicate the default logging, you could output from the callback `Mongoose: ${collectionName}.${methodName}(${methodArgs.join(', ')})`.
  *
  * #### Example:
  *
@@ -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/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/isBsonType.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Get the bson type, if it exists
+ * Determines if `obj` has the given BSON type.
  * @api private
  */
 

package/lib/mongoose.js

@@ -206,8 +206,8 @@ Mongoose.prototype.setDriver = function setDriver(driver) {
 /**
  * Sets mongoose options
  *
- * `key` can be used a object to set multiple options at once.
- * If a error gets thrown for one option, other options will still be evaluated.
+ * `key` can be used as an object to set multiple options at once.
+ * If an error gets thrown for one option, other options will still be evaluated.
  *
  * #### Example:
  *
@@ -247,8 +247,8 @@ Mongoose.prototype.setDriver = function setDriver(driver) {
  * - `translateAliases`: `false` by default. If `true`, Mongoose will automatically translate aliases to their original paths before sending the query to MongoDB.
  * - `updatePipeline`: `false` by default. If `true`, allows passing update pipelines (arrays) to update operations by default without explicitly setting `updatePipeline: true` in each query.
  *
- * @param {string|object} key The name of the option or a object of multiple key-value pairs
- * @param {string|Function|boolean} value The value of the option, unused if "key" is a object
+ * @param {string|object} key The name of the option or an object of multiple key-value pairs
+ * @param {string|Function|boolean} value The value of the option, unused if "key" is an object
  * @returns {Mongoose} The used Mongoose instance
  * @api public
  */
@@ -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) {
@@ -5582,7 +5582,7 @@ Query.prototype[Symbol.asyncIterator] = function queryAsyncIterator() {
  * @see $box https://www.mongodb.com/docs/manual/reference/operator/box/
  * @see within() Query#within https://mongoosejs.com/docs/api/query.html#Query.prototype.within()
  * @see MongoDB Geospatial Indexing https://www.mongodb.com/docs/manual/core/geospatial-indexes/
- * @param {object|Array<number>} val1 Lower Left Coordinates OR a object of lower-left(ll) and upper-right(ur) Coordinates
+ * @param {object|Array<number>} val1 Lower Left Coordinates OR an object of lower-left(ll) and upper-right(ur) Coordinates
  * @param {Array<number>} [val2] Upper Right Coordinates
  * @return {Query} this
  * @api public

package/lib/schema.js

@@ -2253,7 +2253,7 @@ 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)
  *
- * @param {string|object} name The Method Name for a single function, or a Object of "string-function" pairs.
+ * @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
  */
@@ -2298,7 +2298,7 @@ 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.
  *
- * @param {string|object} name The Method Name for a single function, or a Object of "string-function" pairs.
+ * @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
@@ -3119,7 +3119,7 @@ Schema.prototype.toJSONSchema = function toJSONSchema(options) {
   for (const path of Object.keys(this.paths)) {
     const schemaType = this.paths[path];
 
-    // Skip Map embedded paths, maps will be handled seperately.
+    // Skip Map embedded paths, maps will be handled separately.
     if (schemaType._presplitPath.indexOf('$*') !== -1) {
       continue;
     }

package/lib/schemaType.js

@@ -99,11 +99,11 @@ function SchemaType(path, options, instance, parentSchema) {
           const index = this._index;
           if (typeof index === 'object' && index != null) {
             if (index.unique) {
-              throw new Error('Path "' + this.path + '" may not have `index` ' +
+              throw new MongooseError('Path "' + this.path + '" may not have `index` ' +
                 'set to false and `unique` set to true');
             }
             if (index.sparse) {
-              throw new Error('Path "' + this.path + '" may not have `index` ' +
+              throw new MongooseError('Path "' + this.path + '" may not have `index` ' +
                 'set to false and `sparse` set to true');
             }
           }
@@ -317,7 +317,7 @@ SchemaType.prototype.castFunction = function castFunction(caster, message) {
  */
 
 SchemaType.prototype.cast = function cast() {
-  throw new Error('Base SchemaType class does not implement a `cast()` function');
+  throw new MongooseError('Base SchemaType class does not implement a `cast()` function');
 };
 
 /**
@@ -491,7 +491,7 @@ SchemaType.prototype.unique = function unique(value, message) {
     if (!value) {
       return;
     }
-    throw new Error('Path "' + this.path + '" may not have `index` set to ' +
+    throw new MongooseError('Path "' + this.path + '" may not have `index` set to ' +
       'false and `unique` set to true');
   }
 
@@ -530,7 +530,7 @@ SchemaType.prototype.text = function(bool) {
     if (!bool) {
       return this;
     }
-    throw new Error('Path "' + this.path + '" may not have `index` set to ' +
+    throw new MongooseError('Path "' + this.path + '" may not have `index` set to ' +
       'false and `text` set to true');
   }
 
@@ -567,7 +567,7 @@ SchemaType.prototype.sparse = function(bool) {
     if (!bool) {
       return this;
     }
-    throw new Error('Path "' + this.path + '" may not have `index` set to ' +
+    throw new MongooseError('Path "' + this.path + '" may not have `index` set to ' +
       'false and `sparse` set to true');
   }
 
@@ -1003,7 +1003,7 @@ SchemaType.prototype.validate = function(obj, message, type) {
         + arg
         + '. See https://mongoosejs.com/docs/api/schematype.html#SchemaType.prototype.validate()';
 
-      throw new Error(msg);
+      throw new MongooseError(msg);
     }
     this.validate(arg.validator, arg);
   }
@@ -1704,7 +1704,7 @@ SchemaType.prototype.castForQuery = function($conditional, val, context) {
   if ($conditional != null) {
     handler = this.$conditionalHandlers[$conditional];
     if (!handler) {
-      throw new Error('Can\'t use ' + $conditional);
+      throw new MongooseError('Can\'t use ' + $conditional);
     }
     return handler.call(this, val, context);
   }
@@ -1820,7 +1820,7 @@ SchemaType.prototype._duplicateKeyErrorMessage = null;
  */
 
 SchemaType.prototype.toJSONSchema = function toJSONSchema(_options) { // eslint-disable-line no-unused-vars
-  throw new Error(`Converting unsupported SchemaType to JSON Schema: ${this.instance} at path "${this.path}"`);
+  throw new MongooseError(`Converting unsupported SchemaType to JSON Schema: ${this.instance} at path "${this.path}"`);
 };
 
 /**

package/package.json

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

package/types/utility.d.ts

@@ -103,7 +103,7 @@ declare module 'mongoose' {
     ? T
     : Omit<T, keyof U> & U;
 
-  type MergeType<A, B> = Omit<A, keyof B> & B;
+  type MergeType<A, B> = A extends unknown ? Omit<A, keyof B> & B : never;
 
   /**
    * @summary Converts Unions to one record "object".