Merge branch 'master' into 8.1

Author: vkarpov15

CHANGELOG.md

@@ -1,3 +1,27 @@
+8.0.2 / 2023-11-28
+==================
+ * fix(populate): set populated docs in correct order when populating virtual underneath doc array with justOne #14105
+ * fix(populate): fix curPath to update appropriately #14099 #14098 [csy1204](https://github.com/csy1204)
+ * types: make property names show up in intellisense for UpdateQuery #14123 #14090
+ * types(document): correct return type for doc.deleteOne() re: Mongoose 8 breaking change #14110 #14081
+ * types: correct types for when includeResultMetadata: true is set #14078
+ * types(models): allow specifying timestamps as inline option for bulkWrite() operations #14112 #14072
+ * docs: fix rendering of 7.x server compatibility #14086 [laupow](https://github.com/laupow)
+ * docs(source/api): fix "index.js" -> "mongoose.js" rename #14125
+ * docs(README): update breaking change version #14126
+
+7.6.6 / 2023-11-27
+==================
+ * perf: avoid double-running setter logic when calling `push()` #14120 #11380
+ * fix(populate): set populated docs in correct order when populating virtual underneath doc array with justOne #14105 #14018
+ * fix: bump mongodb driver -> 5.9.1 #14084 #13829 [lorand-horvath](https://github.com/lorand-horvath)
+ * types: allow defining document array using [{ prop: String }] syntax #14095 #13424
+ * types: correct types for when includeResultMetadata: true is set #14078 #13987 [prathamVaidya](https://github.com/prathamVaidya)
+ * types(query): base filters and projections off of RawDocType instead of DocType so autocomplete doesn't show populate #14118 #14077
+ * types: make property names show up in intellisense for UpdateQuery #14123 #14090
+ * types(model): support calling Model.validate() with pathsToSkip option #14088 #14003
+ * docs: remove "DEPRECATED" warning mistakenly added to read() tags param #13980
+
 8.0.1 / 2023-11-15
 ==================
  * fix: retain key order with aliases when creating indexes with alias #14042 [meabed](https://github.com/meabed)

CONTRIBUTING.md

@@ -80,10 +80,10 @@ Anyone can file an expense. If the expense makes sense for the development of th
 ### Contributors
 
 Thank you to all the people who have already contributed to mongoose!
-<a href="https://github.com/Automattic/mongoose/graphs/contributors"><img src="https://opencollective.com/mongoose/contributors.svg?width=890" /></a>
+<a href="https://github.com/Automattic/mongoose/graphs/contributors"><img src="https://opencollective.com/mongoose/contributors.svg?width=890" alt="Mongoose contributors" /></a>
 
 ### Backers
 
 Thank you to all our backers! [[Become a backer](https://opencollective.com/mongoose#backer)]
 
-<a href="https://opencollective.com/mongoose#backers" target="_blank"><img src="https://opencollective.com/mongoose/backers.svg?width=890"></a>
+<a href="https://opencollective.com/mongoose#backers" target="_blank"><img src="https://opencollective.com/mongoose/backers.svg?width=890" alt="Mongoose backers"></a>

README.md

@@ -13,7 +13,7 @@ Mongoose is a [MongoDB](https://www.mongodb.org/) object modeling tool designed
 
 The official documentation website is [mongoosejs.com](http://mongoosejs.com/).
 
-Mongoose 7.0.0 was released on February 27, 2023. You can find more details on [backwards breaking changes in 7.0.0 on our docs site](https://mongoosejs.com/docs/migrating_to_7.html).
+Mongoose 8.0.0 was released on October 31, 2023. You can find more details on [backwards breaking changes in 8.0.0 on our docs site](https://mongoosejs.com/docs/migrating_to_8.html).
 
 ## Support
 

docs/further_reading.md

@@ -35,9 +35,9 @@ on this page to make sure it is high quality.
 ## Video Courses
 
 <a href="//pluralsight.pxf.io/c/1321469/432943/7490" class="pluralsight-link">
-  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="" width="180" height="95"/>
+  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="" width="180" height="95" alt="API Design in Node.js Featuring Express & Mongo" />
 </a>
-<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" />
+<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" alt="Pixel" />
 
 <a class="pluralsight-title" href="https://pluralsight.pxf.io/c/1321469/424552/7490?u=https%3A%2F%2Fapp.pluralsight.com%2Flibrary%2Fcourses%2Fapi-design-nodejs-express-mongo%2Ftable-of-contents">
   API Design in Node.js Featuring Express & Mongo
@@ -50,7 +50,7 @@ a serial entrepreneur and former instructor at [Hack Reactor](https://www.hackre
 <hr/>
 
 <a href="https://thinkster.io/tutorials/node-json-api" class="pluralsight-link" style="padding:20px">
-  <img src="https://pbs.twimg.com/profile_images/819400302864412676/6x2g2XtJ_400x400.jpg" alt="" style="width: 140px" />
+  <img src="https://pbs.twimg.com/profile_images/819400302864412676/6x2g2XtJ_400x400.jpg" alt="Building a Production Ready Node.js JSON API" style="width: 140px" />
 </a>
 
 <a class="pluralsight-title" href="https://thinkster.io/tutorials/node-json-api">
@@ -67,9 +67,9 @@ RESTful API with Express and Mongoose from scratch.
 <hr/>
 
 <a href="//pluralsight.pxf.io/c/1321469/432943/7490" class="pluralsight-link">
-  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="" width="180" height="95"/>
+  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="Introduction to Mongoose for Node.js and MongoDB" width="180" height="95"/>
 </a>
-<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" />
+<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" alt="Pixel" />
 
 <a class="pluralsight-title" href="https://pluralsight.pxf.io/c/1321469/424552/7490?u=https%3A%2F%2Fapp.pluralsight.com%2Flibrary%2Fcourses%2Fmongoose-for-nodejs-mongodb%2Ftable-of-contents">
   Introduction to Mongoose for Node.js and MongoDB
@@ -83,9 +83,9 @@ resource for beginners looking to get started.
 <hr/>
 
 <a href="//pluralsight.pxf.io/c/1321469/432943/7490" class="pluralsight-link">
-  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="" width="180" height="95"/>
+  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="RESTful Web Services with Node.js and Express" width="180" height="95"/>
 </a>
-<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" />
+<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" alt="Pixel" />
 
 <a class="pluralsight-title" href="https://pluralsight.pxf.io/c/1321469/424552/7490?u=https%3A%2F%2Fapp.pluralsight.com%2Flibrary%2Fcourses%2Fnode-js-express-rest-web-services%2Ftable-of-contents">
   RESTful Web Services with Node.js and Express
@@ -99,9 +99,9 @@ between *API Design* and *Introduction to Mongoose*. It focuses more on
 <hr/>
 
 <a href="//pluralsight.pxf.io/c/1321469/432943/7490" class="pluralsight-link">
-  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="" width="180" height="95"/>
+  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="Building Business Applications with Vue.js and MongoDB" width="180" height="95"/>
 </a>
-<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" />
+<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" alt="Pixel" />
 
 <a class="pluralsight-title" href="https://pluralsight.pxf.io/c/1321469/424552/7490?u=https%3A%2F%2Fapp.pluralsight.com%2Flibrary%2Fcourses%2Fbuilding-business-applications-vuejs%2Ftable-of-contents">
   Building Business Applications with Vue.js and MongoDB
@@ -116,9 +116,9 @@ learn about frontend dev.
 <hr/>
 
 <a href="//pluralsight.pxf.io/c/1321469/432943/7490" class="pluralsight-link">
-  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="" width="180" height="95"/>
+  <img src="//a.impactradius-go.com/display-ad/7490-432943" alt="Moving Forward with Mongoose.js" width="180" height="95"/>
 </a>
-<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" />
+<img height="0" width="0" src="//pluralsight.pxf.io/i/1321469/432943/7490" style="position:absolute;visibility:hidden;" alt="Pixel" />
 
 <a class="pluralsight-title" href="https://pluralsight.pxf.io/c/1321469/424552/7490?u=https%3A%2F%2Fapp.pluralsight.com%2Flibrary%2Fcourses%2Fmongoosejs-moving-forward%2Ftable-of-contents">
   Moving Forward with Mongoose.js
@@ -133,7 +133,7 @@ so you can upgrade with confidence.
 ## Books
 
 <a class="pluralsight-link" href="http://bit.ly/mongoose-book-2013">
-  <img src="https://s3.amazonaws.com/codebarbarian-images/mongoose.jpg" style="width: 180px">
+  <img src="https://s3.amazonaws.com/codebarbarian-images/mongoose.jpg" style="width: 180px" alt="Mongoose for Application Development">
 </a>
 
 <a class="pluralsight-title" href="http://bit.ly/mongoose-book-2013">
@@ -148,7 +148,7 @@ powerful. Just sub out callbacks for promises.
 <hr/>
 
 <a class="pluralsight-link" href="https://bit.ly/mongodb-schema-design">
-  <img src="https://s3.amazonaws.com/codebarbarian-images/schemadesign.jpg" style="width: 180px">
+  <img src="https://s3.amazonaws.com/codebarbarian-images/schemadesign.jpg" style="width: 180px" alt="The Little MongoDB Schema Design Book">
 </a>
 
 <a class="pluralsight-title" href="https://bit.ly/mongodb-schema-design">
@@ -170,7 +170,7 @@ the book for you.
 ## Blog Posts
 
 <a class="pluralsight-link" style="padding: 20px" href="https://medium.freecodecamp.org/introduction-to-mongoose-for-mongodb-d2a7aa593c57">
-  <img src="https://cdn-images-1.medium.com/max/800/1*uTZXsVta4TwghNobMkZeZg.png" style="width: 140px">
+  <img src="https://cdn-images-1.medium.com/max/800/1*uTZXsVta4TwghNobMkZeZg.png" style="width: 140px" alt="Introduction to Mongoose for MongoDB">
 </a>
 
 <a class="pluralsight-title" href="https://medium.freecodecamp.org/introduction-to-mongoose-for-mongodb-d2a7aa593c57">
@@ -184,7 +184,7 @@ concepts in SQL.
 <hr/>
 
 <a class="pluralsight-link" style="padding: 20px" href="https://developer.mozilla.org/en-US/docs/Learn/Server-side/Express_Nodejs/mongoose">
-  <img src="https://developer.mozilla.org/mdn-social-share.cd6c4a5a.png" style="width: 140px">
+  <img src="https://developer.mozilla.org/mdn-social-share.cd6c4a5a.png" style="width: 140px" alt="Express Tutorial Part 3: Using a Database (with Mongoose)">
 </a>
 
 <a class="pluralsight-title" href="https://developer.mozilla.org/en-US/docs/Learn/Server-side/Express_Nodejs/mongoose">

docs/geojson.md

@@ -115,7 +115,7 @@ the city of Denver, Colorado. It then queries for all documents within
 a polygon representing the state of Colorado using
 [the MongoDB `$geoWithin` operator](https://www.mongodb.com/docs/manual/reference/operator/query/geoWithin/).
 
-<img src="https://i.imgur.com/i32pWnC.png">
+<img src="https://i.imgur.com/i32pWnC.png" alt="Colorado GeoJSON Polygon">
 
 ```acquit
 [require:geojson.*driver query]

docs/jest.md

@@ -86,5 +86,5 @@ Want to learn how to test Mongoose apps correctly? The
 course on Pluralsight has a great section on testing Mongoose apps with [Mocha](http://npmjs.com/package/mocha).
 
 <a href="https://pluralsight.pxf.io/c/1321469/424552/7490?u=https%3A%2F%2Fapp.pluralsight.com%2Flibrary%2Fcourses%2Fnode-js-express-rest-web-services%2Ftable-of-contents">
-  <img src="https://i.imgur.com/KouuaAZ.png">
+  <img src="https://i.imgur.com/KouuaAZ.png" alt="RESTful Web Services with Node.js and Express">
 </a>

docs/migrating_to_8.md

@@ -6,11 +6,12 @@
   }
 </style>
 
-There are several backwards-breaking changes
-you should be aware of when migrating from Mongoose 7.x to Mongoose 8.x.
+There are several backwards-breaking changes you should be aware of when migrating from Mongoose 7.x to Mongoose 8.x.
 
 If you're still on Mongoose 6.x or earlier, please read the [Mongoose 6.x to 7.x migration guide](migrating_to_7.html) and upgrade to Mongoose 7.x first before upgrading to Mongoose 8.
 
+We also recommend reviewing the [MongoDB Node.js driver's release notes for v6.0.0](https://github.com/mongodb/node-mongodb-native/releases/tag/v6.0.0) before upgrading to Mongoose 8.
+
 * [Removed `rawResult` option for `findOneAndUpdate()`](#removed-rawresult-option-for-findoneandupdate)
 * [`Document.prototype.deleteOne()` now returns a query](#document-prototype-deleteone-now-returns-a-query)
 * [MongoDB Node Driver 6.0](#mongodb-node-driver-6)
@@ -65,7 +66,7 @@ const res = await q;
 
 <h2 id="mongodb-node-driver-6"><a href="#mongodb-node-driver-6">MongoDB Node Driver 6</a></h2>
 
-Mongoose 8 uses [v6.x of the MongoDB Node driver](https://github.com/mongodb/node-mongodb-native/blob/main/HISTORY.md#600-2023-08-28).
+Mongoose 8 uses [v6.x of the MongoDB Node driver](https://github.com/mongodb/node-mongodb-native/releases/tag/v6.0.0).
 There's a few noteable changes in MongoDB Node driver v6 that affect Mongoose:
 
 1. The `ObjectId` constructor no longer accepts strings of length 12. In Mongoose 7, `new mongoose.Types.ObjectId('12charstring')` was perfectly valid. In Mongoose 8, `new mongoose.Types.ObjectId('12charstring')` throws an error.

docs/populate.md

@@ -46,7 +46,8 @@ the `Story` model.
   <li><a href="#populate_multiple_documents">Populating multiple existing documents</a></li>
   <li><a href="#deep-populate">Populating across multiple levels</a></li>
   <li><a href="#cross-db-populate">Populating across Databases</a></li>
-  <li><a href="#dynamic-ref">Dynamic References via <code>refPath</code></a></li>
+  <li><a href="#dynamic-refpath">Dynamic References via <code>refPath</code></a></li>
+  <li><a href="#dynamic-ref">Dynamic References via <code>ref</code></a></li>
   <li><a href="#populate-virtuals">Populate Virtuals</a></li>
   <li><a href="#count">Populate Virtuals: The Count Option</a></li>
   <li><a href="#match">Populate Virtuals: The Match Option</a></li>
@@ -469,7 +470,7 @@ const events = await Event.
   populate({ path: 'conversation', model: Conversation });
 ```
 
-<h2 id="dynamic-ref"><a href="#dynamic-ref">Dynamic References via <code>refPath</code></a></h2>
+<h2 id="dynamic-refpath"><a href="#dynamic-refpath">Dynamic References via <code>refPath</code></a></h2>
 
 Mongoose can also populate from multiple collections based on the value
 of a property in the document. Let's say you're building a schema for
@@ -561,6 +562,53 @@ also need an extra `populate()` call for every property, unless you use
 Using `refPath` means you only need 2 schema paths and one `populate()` call
 regardless of how many models your `commentSchema` can point to.
 
+You could also assign a function to `refPath`, which means Mongoose selects a refPath depending on a value on the document being populated.
+
+```javascript
+const commentSchema = new Schema({
+  body: { type: String, required: true },
+  commentType: {
+    type: String,
+    enum: ['comment', 'review']
+  },
+  entityId: {
+    type: Schema.Types.ObjectId,
+    required: true,
+    refPath: function () {
+      return this.commentType === 'review' ? this.reviewEntityModel : this.commentEntityModel; // 'this' refers to the document being populated
+    }
+  },
+  commentEntityModel: {
+    type: String,
+    required: true,
+    enum: ['BlogPost', 'Review']
+  },
+  reviewEntityModel: {
+    type: String,
+    required: true,
+    enum: ['Vendor', 'Product']
+  }
+});
+```
+
+<h2 id="dynamic-ref"><a href="#dynamic-ref">Dynamic References via <code>ref</code></a></h2>
+
+Just like `refPath`, `ref` can also be assigned a function.
+
+```javascript
+const commentSchema = new Schema({
+  body: { type: String, required: true },
+  verifiedBuyer: Boolean
+  doc: {
+    type: Schema.Types.ObjectId,
+    required: true,
+    ref: function() {
+      return this.verifiedBuyer ? 'Product' : 'BlogPost'; // 'this' refers to the document being populated
+    }
+  },
+});
+```
+
 <h2 id="populate-virtuals"><a href="#populate-virtuals">Populate Virtuals</a></h2>
 
 So far you've only populated based on the `_id` field.

docs/promises.md

@@ -60,5 +60,5 @@ better stack traces.
 </i>
 <br><br>
 <a href="http://asyncawait.net/?utm_source=mongoosejs&utm_campaign=promises" style="margin-left: 100px">
-  <img src="/docs/images/asyncawait.png" style="width: 650px" />
+  <img src="/docs/images/asyncawait.png" style="width: 650px" alt="Mastering Async/Await" />
 </a>

docs/source/api.js

@@ -9,7 +9,7 @@ const fs = require('fs');
 const md = require('marked');
 
 const files = [
-  'lib/index.js',
+  'lib/mongoose.js',
   'lib/schema.js',
   'lib/connection.js',
   'lib/document.js',

lib/aggregate.js

@@ -665,7 +665,7 @@ Aggregate.prototype.unionWith = function(options) {
  *     await Model.aggregate(pipeline).read('primaryPreferred');
  *
  * @param {String|ReadPreference} pref one of the listed preference options or their aliases
- * @param {Array} [tags] optional tags for this query. DEPRECATED
+ * @param {Array} [tags] optional tags for this query.
  * @return {Aggregate} this
  * @api public
  * @see mongodb https://www.mongodb.com/docs/manual/applications/replication/#read-preference

lib/schema.js

@@ -1122,15 +1122,14 @@ Schema.prototype.path = function(path, obj) {
       if (_schemaType.$isMongooseDocumentArray) {
         _schemaType.$embeddedSchemaType._arrayPath = arrayPath;
         _schemaType.$embeddedSchemaType._arrayParentPath = path;
-        _schemaType = _schemaType.$embeddedSchemaType.clone();
+        _schemaType = _schemaType.$embeddedSchemaType;
       } else {
         _schemaType.caster._arrayPath = arrayPath;
         _schemaType.caster._arrayParentPath = path;
-        _schemaType = _schemaType.caster.clone();
+        _schemaType = _schemaType.caster;
       }
 
-      _schemaType.path = arrayPath;
-      toAdd.push(_schemaType);
+      this.subpaths[arrayPath] = _schemaType;
     }
 
     for (const _schemaType of toAdd) {

lib/stateMachine.js

@@ -65,7 +65,11 @@ StateMachine.ctor = function() {
  */
 
 StateMachine.prototype._changeState = function _changeState(path, nextState) {
-  const prevBucket = this.states[this.paths[path]];
+  const prevState = this.paths[path];
+  if (prevState === nextState) {
+    return;
+  }
+  const prevBucket = this.states[prevState];
   if (prevBucket) delete prevBucket[path];
 
   this.paths[path] = nextState;