mongoose 9.3.2 → 9.4.0

package/lib/schema/double.js

@@ -7,7 +7,6 @@
 const CastError = require('../error/cast');
 const SchemaType = require('../schemaType');
 const castDouble = require('../cast/double');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 
 /**
  * Double SchemaType constructor.
@@ -231,8 +230,7 @@ Object.defineProperty(SchemaDouble.prototype, '$conditionalHandlers', {
  */
 
 SchemaDouble.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = this.options.required && typeof this.options.required !== 'function';
-  return createJSONSchemaTypeDefinition('number', 'double', options?.useBsonType, isRequired);
+  return this._createJSONSchemaTypeDefinition('number', 'double', options);
 };
 
 SchemaDouble.prototype.autoEncryptionType = function autoEncryptionType() {

package/lib/schema/int32.js

@@ -7,7 +7,6 @@
 const CastError = require('../error/cast');
 const SchemaType = require('../schemaType');
 const castInt32 = require('../cast/int32');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const handleBitwiseOperator = require('./operators/bitwise');
 
 /**
@@ -273,8 +272,7 @@ SchemaInt32.prototype.castForQuery = function($conditional, val, context) {
  */
 
 SchemaInt32.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = this.options.required && typeof this.options.required !== 'function';
-  return createJSONSchemaTypeDefinition('number', 'int', options?.useBsonType, isRequired);
+  return this._createJSONSchemaTypeDefinition('number', 'int', options);
 };
 
 SchemaInt32.prototype.autoEncryptionType = function autoEncryptionType() {

package/lib/schema/map.js

@@ -7,7 +7,6 @@
 const MongooseMap = require('../types/map');
 const SchemaMapOptions = require('../options/schemaMapOptions');
 const SchemaType = require('../schemaType');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const MongooseError = require('../error/mongooseError');
 const Schema = require('../schema');
 const utils = require('../utils');
@@ -125,11 +124,9 @@ class SchemaMap extends SchemaType {
    */
 
   toJSONSchema(options) {
-    const useBsonType = options?.useBsonType;
     const embeddedSchemaType = this.getEmbeddedSchemaType();
 
-    const isRequired = this.options.required && typeof this.options.required !== 'function';
-    const result = createJSONSchemaTypeDefinition('object', 'object', useBsonType, isRequired);
+    const result = this._createJSONSchemaTypeDefinition('object', 'object', options);
     result.additionalProperties = embeddedSchemaType.toJSONSchema(options);
 
     return result;

package/lib/schema/number.js

@@ -8,7 +8,6 @@ const MongooseError = require('../error/index');
 const SchemaNumberOptions = require('../options/schemaNumberOptions');
 const SchemaType = require('../schemaType');
 const castNumber = require('../cast/number');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const handleBitwiseOperator = require('./operators/bitwise');
 const utils = require('../utils');
 
@@ -473,7 +472,7 @@ SchemaNumber.prototype.castForQuery = function($conditional, val, context) {
   if ($conditional != null) {
     handler = this.$conditionalHandlers[$conditional];
     if (!handler) {
-      throw new CastError('number', val, this.path, null, this);
+      throw new MongooseError('Can\'t use ' + $conditional + ' with Number.');
     }
     return handler.call(this, val, context);
   }
@@ -499,8 +498,7 @@ SchemaNumber.prototype.castForQuery = function($conditional, val, context) {
  */
 
 SchemaNumber.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = (this.options.required && typeof this.options.required !== 'function') || this.path === '_id';
-  return createJSONSchemaTypeDefinition('number', 'number', options?.useBsonType, isRequired);
+  return this._createJSONSchemaTypeDefinition('number', 'number', options);
 };
 
 /*!

package/lib/schema/objectId.js

@@ -7,7 +7,6 @@
 const SchemaObjectIdOptions = require('../options/schemaObjectIdOptions');
 const SchemaType = require('../schemaType');
 const castObjectId = require('../cast/objectid');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const getConstructorName = require('../helpers/getConstructorName');
 const oid = require('../types/objectid');
 const isBsonType = require('../helpers/isBsonType');
@@ -318,8 +317,7 @@ function resetId(v) {
  */
 
 SchemaObjectId.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = (this.options.required && typeof this.options.required !== 'function') || this.path === '_id';
-  return createJSONSchemaTypeDefinition('string', 'objectId', options?.useBsonType, isRequired);
+  return this._createJSONSchemaTypeDefinition('string', 'objectId', options);
 };
 
 SchemaObjectId.prototype.autoEncryptionType = function autoEncryptionType() {

package/lib/schema/string.js

@@ -8,7 +8,6 @@ const SchemaType = require('../schemaType');
 const MongooseError = require('../error/index');
 const SchemaStringOptions = require('../options/schemaStringOptions');
 const castString = require('../cast/string');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const utils = require('../utils');
 const isBsonType = require('../helpers/isBsonType');
 
@@ -718,8 +717,7 @@ SchemaString.prototype.castForQuery = function($conditional, val, context) {
  */
 
 SchemaString.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = this.options.required && typeof this.options.required !== 'function';
-  return createJSONSchemaTypeDefinition('string', 'string', options?.useBsonType, isRequired);
+  return this._createJSONSchemaTypeDefinition('string', 'string', options);
 };
 
 SchemaString.prototype.autoEncryptionType = function autoEncryptionType() {

package/lib/schema/subdocument.js

@@ -12,7 +12,6 @@ const SchemaType = require('../schemaType');
 const applyDefaults = require('../helpers/document/applyDefaults');
 const $exists = require('./operators/exists');
 const castToNumber = require('./operators/helpers').castToNumber;
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const discriminator = require('../helpers/model/discriminator');
 const geospatial = require('./operators/geospatial');
 const getConstructor = require('../helpers/discriminator/getConstructor');
@@ -428,9 +427,8 @@ SchemaSubdocument.prototype.clone = function() {
  */
 
 SchemaSubdocument.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = this.options.required && typeof this.options.required !== 'function';
   return {
     ...this.schema.toJSONSchema(options),
-    ...createJSONSchemaTypeDefinition('object', 'object', options?.useBsonType, isRequired)
+    ...this._createJSONSchemaTypeDefinition('object', 'object', options)
   };
 };

package/lib/schema/union.js

@@ -28,6 +28,7 @@ class Union extends SchemaType {
       throw new Error('Union schema type requires an array of types');
     }
     this.schemaTypes = options.of.map(obj => parentSchema.interpretAsType(key, obj, schemaOptions));
+    this.$isSchemaUnion = true;
   }
 
   cast(val, doc, init, prev, options) {
@@ -90,12 +91,61 @@ class Union extends SchemaType {
     throw lastError;
   }
 
+  async doValidate(value, scope, options) {
+    if (options && options.skipSchemaValidators) {
+      if (value != null && typeof value.validate === 'function') {
+        return value.validate();
+      }
+      return;
+    }
+
+    await super.doValidate(value, scope, options);
+    if (value != null && typeof value.validate === 'function') {
+      await value.validate();
+    }
+  }
+
+  doValidateSync(value, scope, options) {
+    if (!options || !options.skipSchemaValidators) {
+      const schemaTypeError = super.doValidateSync(value, scope, options);
+      if (schemaTypeError) {
+        return schemaTypeError;
+      }
+    }
+    if (value != null && typeof value.validateSync === 'function') {
+      return value.validateSync();
+    }
+  }
+
   clone() {
     const schematype = super.clone();
 
     schematype.schemaTypes = this.schemaTypes.map(schemaType => schemaType.clone());
     return schematype;
   }
+
+  /**
+   * Returns this schema type's representation in a JSON schema.
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.useBsonType=false] If true, return a representation with `bsonType` for use with MongoDB's `$jsonSchema`.
+   * @returns {object} JSON schema properties
+   */
+  toJSONSchema(options) {
+    const isRequired = this.options.required && typeof this.options.required !== 'function';
+    const childOptions = { ...options, _overrideRequired: true };
+    const jsonSchemas = this.schemaTypes.map(schemaType => schemaType.toJSONSchema(childOptions));
+    if (isRequired) {
+      return { anyOf: jsonSchemas };
+    }
+
+    return {
+      anyOf: [
+        options?.useBsonType ? { bsonType: 'null' } : { type: 'null' },
+        ...jsonSchemas
+      ]
+    };
+  }
 }
 
 /**

package/lib/schema/uuid.js

@@ -7,7 +7,6 @@
 const SchemaType = require('../schemaType');
 const CastError = SchemaType.CastError;
 const castUUID = require('../cast/uuid');
-const createJSONSchemaTypeDefinition = require('../helpers/createJSONSchemaTypeDefinition');
 const utils = require('../utils');
 const handleBitwiseOperator = require('./operators/bitwise');
 
@@ -290,8 +289,7 @@ SchemaUUID.prototype.castForQuery = function($conditional, val, context) {
  */
 
 SchemaUUID.prototype.toJSONSchema = function toJSONSchema(options) {
-  const isRequired = this.options.required && typeof this.options.required !== 'function';
-  return createJSONSchemaTypeDefinition('string', 'binData', options?.useBsonType, isRequired);
+  return this._createJSONSchemaTypeDefinition('string', 'binData', options);
 };
 
 SchemaUUID.prototype.autoEncryptionType = function autoEncryptionType() {

package/lib/schema.js

@@ -59,7 +59,7 @@ const numberRE = /^\d+$/;
  * - [autoIndex](https://mongoosejs.com/docs/guide.html#autoIndex): bool - defaults to null (which means use the connection's autoIndex option)
  * - [autoCreate](https://mongoosejs.com/docs/guide.html#autoCreate): bool - defaults to null (which means use the connection's autoCreate option)
  * - [bufferCommands](https://mongoosejs.com/docs/guide.html#bufferCommands): bool - defaults to true
- * - [bufferTimeoutMS](https://mongoosejs.com/docs/guide.html#bufferTimeoutMS): number - defaults to 10000 (10 seconds). If `bufferCommands` is enabled, the amount of time Mongoose will wait for connectivity to be restablished before erroring out.
+ * - [bufferTimeoutMS](https://mongoosejs.com/docs/guide.html#bufferTimeoutMS): number - defaults to 10000 (10 seconds). If `bufferCommands` is enabled, the amount of time Mongoose will wait for connectivity to be established before erroring out.
  * - [capped](https://mongoosejs.com/docs/guide.html#capped): bool | number | object - defaults to false
  * - [collection](https://mongoosejs.com/docs/guide.html#collection): string - no default
  * - [discriminatorKey](https://mongoosejs.com/docs/guide.html#discriminatorKey): string - defaults to `__t`
@@ -750,7 +750,7 @@ Schema.prototype.encryptionType = function encryptionType(encryptionType) {
     return this.options.encryptionType;
   }
   if (!(typeof encryptionType === 'string' || encryptionType === null)) {
-    throw new MongooseError('invalid `encryptionType`: ${encryptionType}');
+    throw new MongooseError(`invalid \`encryptionType\`: ${encryptionType}`);
   }
   this.options.encryptionType = encryptionType;
 };
@@ -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');
             }
           }
@@ -181,6 +181,39 @@ SchemaType.prototype.toJSON = function toJSON() {
   return res;
 };
 
+/**
+ * Helper for creating `{ type: 'object' }` vs `{ bsonType: 'object' }` vs nullable variants.
+ *
+ * @param {string} type
+ * @param {string} bsonType
+ * @param {object} [options]
+ * @param {boolean} [options.useBsonType=false]
+ * @param {boolean} [options._defaultRequired=false]
+ * @param {boolean} [options._overrideRequired]
+ * @returns {object}
+ * @api private
+ */
+
+SchemaType.prototype._createJSONSchemaTypeDefinition = function _createJSONSchemaTypeDefinition(type, bsonType, options) {
+  const useBsonType = options?.useBsonType;
+  const isRequired = options?._overrideRequired ??
+    (this.options.required == null ?
+      (options?._defaultRequired === true || this.path === '_id') :
+      this.options.required && typeof this.options.required !== 'function');
+
+  if (useBsonType) {
+    if (isRequired) {
+      return { bsonType };
+    }
+    return { bsonType: [bsonType, 'null'] };
+  }
+
+  if (isRequired) {
+    return { type };
+  }
+  return { type: [type, 'null'] };
+};
+
 /**
  * The validators that Mongoose should run to validate properties at this SchemaType's path.
  *
@@ -317,7 +350,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');
 };
 
 /**
@@ -380,10 +413,10 @@ SchemaType.get = function(getter) {
  * #### Example:
  *
  *     // values are cast:
- *     const schema = new Schema({ aNumber: { type: Number, default: 4.815162342 }})
+ *     const schema = new Schema({ num: { type: Number, default: 4.815162342 }})
  *     const M = db.model('M', schema)
  *     const m = new M;
- *     console.log(m.aNumber) // 4.815162342
+ *     console.log(m.num) // 4.815162342
  *
  *     // default unique objects for Mixed types:
  *     const schema = new Schema({ mixed: Schema.Types.Mixed });
@@ -491,7 +524,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 +563,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 +600,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');
   }
 
@@ -786,7 +819,7 @@ SchemaType.prototype.set = function(fn) {
  *     // defining within the schema
  *     const s = new Schema({ born: { type: Date, get: dob })
  *
- *     // or by retreiving its SchemaType
+ *     // or by retrieving its SchemaType
  *     const s = new Schema({ born: Date })
  *     s.path('born').get(dob)
  *
@@ -936,7 +969,7 @@ SchemaType.prototype.validateAll = function(validators) {
  *       }
  *     });
  *
- * You might use asynchronous validators to retreive other documents from the database to validate against or to meet other I/O bound validation needs.
+ * You might use asynchronous validators to retrieve other documents from the database to validate against or to meet other I/O bound validation needs.
  *
  * Validation occurs `pre('save')` or whenever you manually execute [document#validate](https://mongoosejs.com/docs/api/document.html#Document.prototype.validate()).
  *
@@ -1003,7 +1036,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 +1737,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 +1853,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/lib/types/array/methods/index.js

@@ -572,7 +572,7 @@ const methods = {
    *
    * #### Note:
    *
-   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
+   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwriting any changes that happen between when you retrieved the object and when you save it._
    *
    * @param {...any} [args]
    * @api public
@@ -830,7 +830,7 @@ const methods = {
    *
    * #### Note:
    *
-   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
+   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwriting any changes that happen between when you retrieved the object and when you save it._
    *
    * @api public
    * @method shift
@@ -850,7 +850,7 @@ const methods = {
    *
    * #### Note:
    *
-   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
+   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwriting any changes that happen between when you retrieved the object and when you save it._
    *
    * @api public
    * @method sort
@@ -870,7 +870,7 @@ const methods = {
    *
    * #### Note:
    *
-   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
+   * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwriting any changes that happen between when you retrieved the object and when you save it._
    *
    * @api public
    * @method splice

package/lib/utils.js

@@ -119,6 +119,16 @@ exports.deepEqual = function deepEqual(a, b) {
       deepEqual(Array.from(a.values()), Array.from(b.values()));
   }
 
+  if (a instanceof Set || b instanceof Set) {
+    if (!(a instanceof Set) || !(b instanceof Set)) {
+      return false;
+    }
+    if (a.size !== b.size) {
+      return false;
+    }
+    return deepEqual(Array.from(a.values()), Array.from(b.values()));
+  }
+
   // Handle MongooseNumbers
   if (a instanceof Number && b instanceof Number) {
     return a.valueOf() === b.valueOf();
@@ -313,8 +323,8 @@ exports.merge = function merge(to, from, options, path) {
         // base schema has a given path as a single nested but discriminator schema
         // has the path as a document array, or vice versa (gh-9534)
         if (options.isDiscriminatorSchemaMerge &&
-            (from[key].$isSingleNested && to[key].$isMongooseDocumentArray) ||
-            (from[key].$isMongooseDocumentArray && to[key].$isSingleNested)) {
+            ((from[key].$isSingleNested && to[key].$isMongooseDocumentArray) ||
+            (from[key].$isMongooseDocumentArray && to[key].$isSingleNested))) {
           continue;
         } else if (from[key].instanceOfSchema) {
           if (to[key].instanceOfSchema) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "9.3.2",
+  "version": "9.4.0",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -37,11 +37,11 @@
     "acquit-require": "0.1.1",
     "ajv": "8.18.0",
     "c8": "11.0.0",
-    "cheerio": "^1.2",
+    "cheerio": "1.2.0",
     "dox": "1.0.0",
     "eslint": "10.0.2",
     "eslint-plugin-mocha-no-only": "1.2.0",
-    "express": "^4.19.2",
+    "express": "4.22.1",
     "fs-extra": "~11.3.0",
     "globals": "^17.4.0",
     "glob": "^13.0.6",
@@ -60,7 +60,7 @@
     "ncp": "^2.0.0",
     "pug": "3.0.3",
     "sinon": "21.0.1",
-    "tstyche": "^6.2.0",
+    "tstyche": "^7.0.0-rc.0",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.31.1",
     "uuid": "11.1.0"
@@ -80,7 +80,7 @@
     "docs:generate:sponsorData": "node ./scripts/loadSponsorData.js",
     "docs:test": "npm run docs:generate",
     "docs:view": "node ./scripts/static.js",
-    "docs:prepare:publish:stable": "git checkout gh-pages && git merge master && npm run docs:generate",
+    "docs:prepare:publish:stable": "git checkout gh-pages && git merge master && env GENERATE_SEARCH=true npm run docs:generate",
     "docs:prepare:publish:5x": "git checkout 5.x && git merge 5.x && npm run docs:clean:stable && npm run docs:generate && npm run docs:copy:tmp && git checkout gh-pages && npm run docs:copy:tmp:5x",
     "docs:prepare:publish:6x": "git checkout 6.x && git merge 6.x && npm run docs:clean:stable && env DOCS_DEPLOY=true npm run docs:generate && mv ./docs/6.x ./tmp && git checkout gh-pages && npm run docs:copy:tmp:6x",
     "docs:prepare:publish:7x": "env DOCS_DEPLOY=true npm run docs:generate && git checkout gh-pages && rm -rf ./docs/7.x && mv ./tmp ./docs/7.x",
@@ -90,7 +90,7 @@
     "lint": "eslint .",
     "lint-js": "eslint . --ext .js --ext .cjs",
     "lint-ts": "eslint . --ext .ts",
-    "lint-md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#benchmarks\"",
+    "lint-md": "markdownlint-cli2 \"docs/**/*.md\" \"docs/*.md\" \"*.md\"",
     "release": "git pull && git push origin master --tags && npm publish",
     "release-5x": "git pull origin 5.x && git push origin 5.x && git push origin 5.x --tags && npm publish --tag 5x",
     "release-6x": "git pull origin 6.x && git push origin 6.x && git push origin 6.x --tags && npm publish --tag 6x",

package/types/document.d.ts

@@ -32,7 +32,7 @@ declare module 'mongoose' {
     _id: T;
 
     /** Assert that a given path or paths is populated. Throws an error if not populated. */
-    $assertPopulated<Paths = {}>(path: string | string[], values?: Partial<Paths>): Omit<this, keyof Paths> & Paths;
+    $assertPopulated<Paths = {}>(path: string | string[], values?: Partial<Paths>): PopulateDocumentResult<this, Paths, PopulatedPathsDocumentType<DocType, Paths>, DocType>;
 
     /** Clear the document's modified paths. */
     $clearModifiedPaths(): this;
@@ -171,6 +171,13 @@ declare module 'mongoose' {
      * Returns the changes that happened to the document
      * in the format that will be sent to MongoDB.
      */
+    $getChanges(): UpdateQuery<this>;
+
+    /**
+     * Returns the changes that happened to the document
+     * in the format that will be sent to MongoDB.
+     * @deprecated Use `$getChanges()` instead.
+     */
     getChanges(): UpdateQuery<this>;
 
     /** Signal that we desire an increment of this documents version. */
@@ -238,8 +245,8 @@ declare module 'mongoose' {
     $parent(): Document | undefined;
 
     /** Populates document references. */
-    populate<Paths = {}>(path: string | PopulateOptions | (string | PopulateOptions)[]): Promise<MergeType<this, Paths>>;
-    populate<Paths = {}>(path: string, select?: string | AnyObject, model?: Model<any>, match?: AnyObject, options?: PopulateOptions): Promise<MergeType<this, Paths>>;
+    populate<Paths = {}>(path: string | PopulateOptions | (string | PopulateOptions)[]): Promise<PopulateDocumentResult<this, Paths, PopulatedPathsDocumentType<DocType, Paths>, DocType>>;
+    populate<Paths = {}>(path: string, select?: string | AnyObject, model?: Model<any>, match?: AnyObject, options?: PopulateOptions): Promise<PopulateDocumentResult<this, Paths, PopulatedPathsDocumentType<DocType, Paths>, DocType>>;
 
     /** Gets _id(s) used during population of the given `path`. If the path was not populated, returns `undefined`. */
     populated(path: string): any;
@@ -262,11 +269,41 @@ declare module 'mongoose' {
     toBSON(): Require_id<DocType>;
 
     /** The return value of this method is used in calls to JSON.stringify(doc). */
+    toJSON<PopulatedRawDocType, DepopulatedRawDocType>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, DepopulatedRawDocType>,
+      options: { depopulate: true }
+    ): Default__v<Require_id<DepopulatedRawDocType>, TSchemaOptions>;
+    toJSON<PopulatedRawDocType, DepopulatedRawDocType, O extends ToObjectOptions & { depopulate: true }>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, DepopulatedRawDocType>,
+      options: O
+    ): ToObjectReturnType<DepopulatedRawDocType, TVirtuals, O, TSchemaOptions>;
+    toJSON<PopulatedRawDocType, O extends ToObjectOptions>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, any>,
+      options: O
+    ): ToObjectReturnType<PopulatedRawDocType, TVirtuals, O, TSchemaOptions>;
+    toJSON<PopulatedRawDocType>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, any>
+    ): Default__v<Require_id<PopulatedRawDocType>, TSchemaOptions>;
     toJSON<O extends ToObjectOptions>(options: O): ToObjectReturnType<DocType, TVirtuals, O, TSchemaOptions>;
     toJSON(options?: ToObjectOptions): Default__v<Require_id<DocType>, TSchemaOptions>;
     toJSON<T>(options?: ToObjectOptions): Default__v<Require_id<T>, ResolveSchemaOptions<TSchemaOptions>>;
 
     /** Converts this document into a plain-old JavaScript object ([POJO](https://masteringjs.io/tutorials/fundamentals/pojo)). */
+    toObject<PopulatedRawDocType, DepopulatedRawDocType>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, DepopulatedRawDocType>,
+      options: { depopulate: true }
+    ): Default__v<Require_id<DepopulatedRawDocType>, TSchemaOptions>;
+    toObject<PopulatedRawDocType, DepopulatedRawDocType, O extends ToObjectOptions & { depopulate: true }>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, DepopulatedRawDocType>,
+      options: O
+    ): ToObjectReturnType<DepopulatedRawDocType, TVirtuals, O, TSchemaOptions>;
+    toObject<PopulatedRawDocType, O extends ToObjectOptions>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, any>,
+      options: O
+    ): ToObjectReturnType<PopulatedRawDocType, TVirtuals, O, TSchemaOptions>;
+    toObject<PopulatedRawDocType>(
+      this: PopulatedDocumentMarker<PopulatedRawDocType, any>
+    ): Default__v<Require_id<PopulatedRawDocType>, TSchemaOptions>;
     toObject<O extends ToObjectOptions>(options: O): ToObjectReturnType<DocType, TVirtuals, O, TSchemaOptions>;
     toObject(options?: ToObjectOptions): Default__v<Require_id<DocType>, TSchemaOptions>;
     toObject<T>(options?: ToObjectOptions): Default__v<Require_id<T>, ResolveSchemaOptions<TSchemaOptions>>;

package/types/index.d.ts

@@ -177,13 +177,25 @@ declare module 'mongoose' {
     HydratedDocPathsType,
     any,
     TOverrides extends Record<string, never> ?
-      Document<unknown, TQueryHelpers, RawDocType, TVirtuals, TSchemaOptions> & Default__v<Require_id<HydratedDocPathsType>, TSchemaOptions> & AddDefaultId<HydratedDocPathsType, {}, TSchemaOptions> :
+      Document<unknown, TQueryHelpers, RawDocType, TVirtuals, TSchemaOptions> &
+      Default__v<Require_id<HydratedDocPathsType>, TSchemaOptions> &
+      IfEquals<
+        TVirtuals,
+        {},
+        AddDefaultId<HydratedDocPathsType, {}, TSchemaOptions>,
+        TVirtuals
+      > :
       IfAny<
         TOverrides,
         Document<unknown, TQueryHelpers, RawDocType, TVirtuals, TSchemaOptions> & Default__v<Require_id<HydratedDocPathsType>, TSchemaOptions>,
         Document<unknown, TQueryHelpers, RawDocType, TVirtuals, TSchemaOptions> & MergeType<
           Default__v<Require_id<HydratedDocPathsType>, TSchemaOptions>,
-          TOverrides
+          IfEquals<
+            TOverrides,
+            {},
+            TOverrides,
+            TOverrides & AddDefaultId<HydratedDocPathsType, TVirtuals, TSchemaOptions>
+          >
         >
       >
   >;
@@ -1094,6 +1106,9 @@ declare module 'mongoose' {
     // Handle DocumentArray - recurse into items
     : T extends Types.DocumentArray<infer ItemType>
       ? Types.DocumentArray<ApplyFlattenTransforms<ItemType, O>>
+    // Handle plain arrays - recurse into items
+    : T extends Array<infer ItemType>
+      ? ApplyFlattenTransforms<ItemType, O>[]
     // Handle Subdocument - recurse into subdoc type
     : T extends Types.Subdocument<unknown, unknown, infer SubdocType>
       ? HydratedSingleSubdocument<ApplyFlattenTransforms<SubdocType, O>>