Merge branch 'master' into 8.18

vkarpov15 · vkarpov15 · commit a59c33bd8e68 · 2025-08-19T15:12:02.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,10 @@
+8.17.2 / 2025-08-18
+===================
+ * fix: avoid Model.validate() hanging when all paths fail casting #15580 #15579 [piotracalski](https://github.com/piotracalski)
+ * types(document): better support for flattenObjectIds and versionKey options for toObject() and toJSON() #15582 #15578
+ * docs: fix docs jsdoc tags and add UUID to be listed #15585
+ * docs(document): fix code sample that errors with "Cannot set properties of undefined" #15589
+
 8.17.1 / 2025-08-07
 ===================
  * fix(query): propagate read preference and read concern to populate if read() called after populate() #15567 #15553
diff --git a/docs/source/api.js b/docs/source/api.js
@@ -29,6 +29,7 @@ const files = [
   'lib/schema/number.js',
   'lib/schema/objectId.js',
   'lib/schema/string.js',
+  'lib/schema/uuid.js',
   'lib/options/schemaTypeOptions.js',
   'lib/options/schemaArrayOptions.js',
   'lib/options/schemaBufferOptions.js',
@@ -42,7 +43,8 @@ const files = [
   'lib/types/buffer.js',
   'lib/types/decimal128.js',
   'lib/types/map.js',
-  'lib/types/array/methods/index.js'
+  'lib/types/array/methods/index.js',
+  'lib/types/uuid.js'
 ];
 
 /** @type {Map.<string, DocsObj>} */
diff --git a/lib/document.js b/lib/document.js
@@ -4070,15 +4070,17 @@ Document.prototype.$__toObjectShallow = function $__toObjectShallow(schemaFields
  *
  * If you want to skip transformations, use `transform: false`:
  *
- *     schema.options.toObject.hide = '_id';
- *     schema.options.toObject.transform = function (doc, ret, options) {
- *       if (options.hide) {
- *         options.hide.split(' ').forEach(function (prop) {
- *           delete ret[prop];
- *         });
+ *     schema.options.toObject = {
+ *       hide: '_id',
+ *       transform: function(doc, ret, options) {
+ *         if (options.hide) {
+ *           options.hide.split(' ').forEach(function(prop) {
+ *             delete ret[prop];
+ *           });
+ *         }
+ *         return ret;
  *       }
- *       return ret;
- *     }
+ *     };
  *
  *     const doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' });
  *     doc.toObject();                                        // { secret: 47, name: 'Wreck-it Ralph' }
diff --git a/lib/schema/array.js b/lib/schema/array.js
@@ -654,6 +654,8 @@ function cast$elemMatch(val, context) {
  * For example, `$conditionalHandlers.$all` is the function Mongoose calls to cast `$all` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaArray
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/bigint.js b/lib/schema/bigint.js
@@ -100,7 +100,7 @@ SchemaBigInt.get = SchemaType.get;
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -190,6 +190,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$in` is the function Mongoose calls to cast `$in` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaBigInt
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/boolean.js b/lib/schema/boolean.js
@@ -105,7 +105,7 @@ SchemaBoolean.get = SchemaType.get;
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -242,6 +242,8 @@ const $conditionalHandlers = { ...SchemaType.prototype.$conditionalHandlers };
  * For example, `$conditionalHandlers.$in` is the function Mongoose calls to cast `$in` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaBoolean
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/buffer.js b/lib/schema/buffer.js
@@ -276,6 +276,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$exists` is the function Mongoose calls to cast `$exists` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaBuffer
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/date.js b/lib/schema/date.js
@@ -111,7 +111,7 @@ SchemaDate.get = SchemaType.get;
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -402,6 +402,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$gte` is the function Mongoose calls to cast `$gte` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaDate
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/decimal128.js b/lib/schema/decimal128.js
@@ -227,6 +227,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$lte` is the function Mongoose calls to cast `$lte` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaDecimal128
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/documentArray.js b/lib/schema/documentArray.js
@@ -122,6 +122,8 @@ SchemaDocumentArray.prototype.OptionsConstructor = SchemaDocumentArrayOptions;
  * For example, `$conditionalHandlers.$size` is the function Mongoose calls to cast `$size` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaDocumentArray
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/double.js b/lib/schema/double.js
@@ -115,7 +115,7 @@ SchemaDouble._defaultCaster = v => {
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -210,6 +210,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$lt` is the function Mongoose calls to cast `$lt` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaDouble
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/int32.js b/lib/schema/int32.js
@@ -119,7 +119,7 @@ SchemaInt32._defaultCaster = v => {
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -214,6 +214,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$gt` is the function Mongoose calls to cast `$gt` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaInt32
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/number.js b/lib/schema/number.js
@@ -93,7 +93,7 @@ SchemaNumber._cast = castNumber;
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -418,6 +418,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$gte` is the function Mongoose calls to cast `$gte` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaNumber
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/objectId.js b/lib/schema/objectId.js
@@ -143,7 +143,7 @@ SchemaObjectId._cast = castObjectId;
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -273,6 +273,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$in` is the function Mongoose calls to cast `$in` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaObjectId
+ * @instance
  * @api public
  */
 
@@ -310,6 +312,7 @@ function resetId(v) {
  * @param [options]
  * @param [options.useBsonType=false] If true, return a representation with `bsonType` for use with MongoDB's `$jsonSchema`.
  * @returns {Object} JSON schema properties
+ * @api public
  */
 
 SchemaObjectId.prototype.toJSONSchema = function toJSONSchema(options) {
diff --git a/lib/schema/string.js b/lib/schema/string.js
@@ -75,7 +75,7 @@ SchemaString._cast = castString;
  *
  * @param {Function} caster
  * @return {Function}
- * @function get
+ * @function cast
  * @static
  * @api public
  */
@@ -665,6 +665,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$exists` is the function Mongoose calls to cast `$exists` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaString
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/subdocument.js b/lib/schema/subdocument.js
@@ -158,6 +158,8 @@ $conditionalHandlers.$exists = $exists;
  * For example, `$conditionalHandlers.$exists` is the function Mongoose calls to cast `$exists` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaSubdocument
+ * @instance
  * @api public
  */
 
diff --git a/lib/schema/uuid.js b/lib/schema/uuid.js
@@ -263,6 +263,8 @@ const $conditionalHandlers = {
  * For example, `$conditionalHandlers.$exists` is the function Mongoose calls to cast `$exists` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaUUID
+ * @instance
  * @api public
  */
 
diff --git a/lib/schemaType.js b/lib/schemaType.js
@@ -1655,6 +1655,8 @@ function handle$in(val, context) {
  * For example, `$conditionalHandlers.$exists` is the function Mongoose calls to cast `$exists` filter operators.
  *
  * @property $conditionalHandlers
+ * @memberOf SchemaType
+ * @instance
  * @api public
  */
 
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "8.17.1",
+  "version": "8.17.2",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
diff --git a/test/document.test.js b/test/document.test.js
@@ -14586,6 +14586,35 @@ describe('document', function() {
     assert.strictEqual(updatedItem.nested.get('inserted').map.get('a1'), 1);
     assert.strictEqual(updatedItem.nested.get('inserted2').map.get('a1'), 1);
   });
+
+  it('removes versionKey from output if versionKey: false set on toObject() or toJSON() (gh-15578)', async function() {
+    const schema = new mongoose.Schema({ name: String }, { versionKey: '__v' });
+    const Model = db.model('Test', schema);
+
+    const doc = await Model.create({ name: 'test' });
+
+    // Default: versionKey present
+    let obj = doc.toObject();
+    assert.ok(obj.hasOwnProperty('__v'));
+
+    obj = doc.toObject();
+    assert.ok(obj.hasOwnProperty('__v'));
+
+    // toObject({ versionKey: false }) removes versionKey
+    obj = doc.toObject({ versionKey: false });
+    assert.ok(!obj.hasOwnProperty('__v'));
+
+    // toJSON({ versionKey: false }) removes versionKey
+    obj = doc.toJSON({ versionKey: false });
+    assert.ok(!obj.hasOwnProperty('__v'));
+
+    // If versionKey: false in schema, versionKey should not be present
+    const schemaNoVersion = new mongoose.Schema({ name: String }, { versionKey: false });
+    const ModelNoVersion = db.model('TestNoVersion', schemaNoVersion);
+    const docNoVersion = await ModelNoVersion.create({ name: 'test2' });
+    obj = docNoVersion.toObject();
+    assert.ok(!obj.hasOwnProperty('__v'));
+  });
 });
 
 describe('Check if instance function that is supplied in schema option is available', function() {
diff --git a/test/model.discriminator.test.js b/test/model.discriminator.test.js
@@ -1626,9 +1626,9 @@ describe('model', function() {
 
     const post = await Post.create({});
 
-    await UserWithPost.create({ postId: post._id });
+    const { _id } = await UserWithPost.create({ postId: post._id });
 
-    const user = await User.findOne().populate({ path: 'post' });
+    const user = await User.findById(_id).populate({ path: 'post' });
 
     assert.ok(user.postId);
   });
diff --git a/test/types/document.test.ts b/test/types/document.test.ts
diff --git a/test/types/schema.test.ts b/test/types/schema.test.ts
diff --git a/types/document.d.ts b/types/document.d.ts
diff --git a/types/index.d.ts b/types/index.d.ts

Original file line number	Diff line number	Diff line change
`@@ -654,6 +654,8 @@ function cast$elemMatch(val, context) {`
`654`	`654`	* For example, `$conditionalHandlers.$all` is the function Mongoose calls to cast `$all` filter operators.
`655`	`655`	`*`
`656`	`656`	`* @property $conditionalHandlers`
	`657`	`+ * @memberOf SchemaArray`
	`658`	`+ * @instance`
`657`	`659`	`* @api public`
`658`	`660`	`*/`
`659`	`661`
Original file line number	Diff line number	Diff line change
`@@ -276,6 +276,8 @@ const $conditionalHandlers = {`
`276`	`276`	* For example, `$conditionalHandlers.$exists` is the function Mongoose calls to cast `$exists` filter operators.
`277`	`277`	`*`
`278`	`278`	`* @property $conditionalHandlers`
	`279`	`+ * @memberOf SchemaBuffer`
	`280`	`+ * @instance`
`279`	`281`	`* @api public`
`280`	`282`	`*/`
`281`	`283`
Original file line number	Diff line number	Diff line change
`@@ -227,6 +227,8 @@ const $conditionalHandlers = {`
`227`	`227`	* For example, `$conditionalHandlers.$lte` is the function Mongoose calls to cast `$lte` filter operators.
`228`	`228`	`*`
`229`	`229`	`* @property $conditionalHandlers`
	`230`	`+ * @memberOf SchemaDecimal128`
	`231`	`+ * @instance`
`230`	`232`	`* @api public`
`231`	`233`	`*/`
`232`	`234`
Original file line number	Diff line number	Diff line change
`@@ -122,6 +122,8 @@ SchemaDocumentArray.prototype.OptionsConstructor = SchemaDocumentArrayOptions;`
`122`	`122`	* For example, `$conditionalHandlers.$size` is the function Mongoose calls to cast `$size` filter operators.
`123`	`123`	`*`
`124`	`124`	`* @property $conditionalHandlers`
	`125`	`+ * @memberOf SchemaDocumentArray`
	`126`	`+ * @instance`
`125`	`127`	`* @api public`
`126`	`128`	`*/`
`127`	`129`