Merge branch 'master' into vkarpov15/gh-14289

Author: vkarpov15

.github/workflows/test.yml

@@ -67,7 +67,7 @@ jobs:
 
       - name: Load MongoDB binary cache
         id: cache-mongodb-binaries
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ~/.cache/mongodb-binaries
           key: ${{ matrix.os }}-${{ matrix.mongodb }}
@@ -101,7 +101,7 @@ jobs:
           node-version: 16
       - name: Load MongoDB binary cache
         id: cache-mongodb-binaries
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ~/.cache/mongodb-binaries
           key: deno-${{ env.MONGOMS_VERSION }}
@@ -141,4 +141,4 @@ jobs:
       - name: Check out repo
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Dependency review
-        uses: actions/dependency-review-action@v3
+        uses: actions/dependency-review-action@v4

CHANGELOG.md

@@ -1,3 +1,36 @@
+7.6.9 / 2024-02-26
+==================
+ * fix(document): handle embedded recursive discriminators on nested path defined using Schema.prototype.discriminator #14256 #14245
+ * types(model): correct return type for findByIdAndDelete() #14233 #14190
+ * docs(connections): add note about using asPromise() with createConnection() for error handling #14364 #14266
+ * docs(model+query+findoneandupdate): add more details about overwriteDiscriminatorKey option to docs #14264 #14246
+
+8.2.0 / 2024-02-22
+==================
+ * feat(model): add recompileSchema() function to models to allow applying schema changes after compiling #14306 #14296
+ * feat: add middleware for bulkWrite() and createCollection() #14358 #14263 #7893
+ * feat(model): add `hydratedPopulatedDocs` option to make hydrate recursively hydrate populated docs #14352 #4727
+ * feat(connection): add withSession helper #14339 #14330
+
+8.1.3 / 2024-02-16
+==================
+ * fix: avoid corrupting $set-ed arrays when transaction error occurs #14346 #14340
+ * fix(populate): handle ref() functions that return a model instance #14343 #14249
+ * fix: insert version key when using insertMany even if `toObject.versionKey` set to false #14344
+ * fix(cursor): make aggregation cursor support transform option to match query cursor #14348 #14331
+ * docs(document): clarify that transform function option applies to subdocs #13757
+
+8.1.2 / 2024-02-08
+==================
+ * fix: include virtuals in document array toString() output if toObject.virtuals set #14335 #14315
+ * fix(document): handle setting nested path to spread doc with extra properties #14287 #14269
+ * fix(populate): call setter on virtual populated path with populated doc instead of undefined #14314
+ * fix(QueryCursor): remove callback parameter of AggregationCursor and QueryCursor #14299 [DevooKim](https://github.com/DevooKim)
+ * types: add typescript support for arbitrary fields for the options parameter of Model functions which are of type MongooseQueryOptions #14342 #14341 [FaizBShah](https://github.com/FaizBShah)
+ * types(model): correct return type for findOneAndUpdate with includeResultMetadata and lean set #14336 #14303
+ * types(connection): add type definition for `createCollections()` #14295 #14279
+ * docs(timestamps): clarify that replaceOne() and findOneAndReplace() overwrite timestamps #14337 #14309
+
 8.1.1 / 2024-01-24
 ==================
  * fix(model): throw readable error when calling Model() with a string instead of model() #14288 #14281

docs/connections.md

@@ -426,16 +426,24 @@ The `mongoose.createConnection()` function takes the same arguments as
 const conn = mongoose.createConnection('mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]', options);
 ```
 
-This [connection](api/connection.html#connection_Connection) object is then used to
-create and retrieve [models](api/model.html#model_Model). Models are
-**always** scoped to a single connection.
+This [connection](api/connection.html#connection_Connection) object is then used to create and retrieve [models](api/model.html#model_Model).
+Models are **always** scoped to a single connection.
 
 ```javascript
 const UserModel = conn.model('User', userSchema);
 ```
 
-If you use multiple connections, you should make sure you export schemas,
-**not** models. Exporting a model from a file is called the *export model pattern*.
+The `createConnection()` function returns a connection instance, not a promise.
+If you want to use `await` to make sure Mongoose successfully connects to MongoDB, use the [`asPromise()` function](api/connection.html#Connection.prototype.asPromise()):
+
+```javascript
+// `asPromise()` returns a promise that resolves to the connection
+// once the connection succeeds, or rejects if connection failed.
+const conn = await mongoose.createConnection(connectionString).asPromise();
+```
+
+If you use multiple connections, you should make sure you export schemas, **not** models.
+Exporting a model from a file is called the *export model pattern*.
 The export model pattern is limited because you can only use one connection.
 
 ```javascript

docs/middleware.md

@@ -67,13 +67,17 @@ Model middleware is supported for the following model functions.
 Don't confuse model middleware and document middleware: model middleware hooks into *static* functions on a `Model` class, document middleware hooks into *methods* on a `Model` class.
 In model middleware functions, `this` refers to the model.
 
+* [bulkWrite](api/model.html#model_Model-bulkWrite)
+* [createCollection](api/model.html#model_Model-createCollection)
 * [insertMany](api/model.html#model_Model-insertMany)
 
 Here are the possible strings that can be passed to `pre()`
 
 * aggregate
+* bulkWrite
 * count
 * countDocuments
+* createCollection
 * deleteOne
 * deleteMany
 * estimatedDocumentCount

docs/timestamps.md

@@ -47,6 +47,7 @@ console.log(doc.updatedAt); // 2022-02-26T17:08:13.991Z
 
 // Mongoose also blocks changing `createdAt` and sets its own `updatedAt`
 // on `findOneAndUpdate()`, `updateMany()`, and other query operations
+// **except** `replaceOne()` and `findOneAndReplace()`.
 doc = await User.findOneAndUpdate(
   { _id: doc._id },
   { name: 'test3', createdAt: new Date(0), updatedAt: new Date(0) },
@@ -56,6 +57,35 @@ console.log(doc.createdAt); // 2022-02-26T17:08:13.930Z
 console.log(doc.updatedAt); // 2022-02-26T17:08:14.008Z
 ```
 
+Keep in mind that `replaceOne()` and `findOneAndReplace()` overwrite all non-`_id` properties, **including** immutable properties like `createdAt`.
+Calling `replaceOne()` or `findOneAndReplace()` will update the `createdAt` timestamp as shown below.
+
+```javascript
+// `findOneAndReplace()` and `replaceOne()` without timestamps specified in `replacement`
+// sets `createdAt` and `updatedAt` to current time.
+doc = await User.findOneAndReplace(
+  { _id: doc._id },
+  { name: 'test3' },
+  { new: true }
+);
+console.log(doc.createdAt); // 2022-02-26T17:08:14.008Z
+console.log(doc.updatedAt); // 2022-02-26T17:08:14.008Z
+
+// `findOneAndReplace()` and `replaceOne()` with timestamps specified in `replacement`
+// sets `createdAt` and `updatedAt` to the values in `replacement`.
+doc = await User.findOneAndReplace(
+  { _id: doc._id },
+  {
+    name: 'test3',
+    createdAt: new Date('2022-06-01'),
+    updatedAt: new Date('2022-06-01')
+  },
+  { new: true }
+);
+console.log(doc.createdAt); // 2022-06-01T00:00:00.000Z
+console.log(doc.updatedAt); // 2022-06-01T00:00:00.000Z
+```
+
 ## Alternate Property Names
 
 For the purposes of these docs, we'll always refer to `createdAt` and `updatedAt`.

docs/tutorials/findoneandupdate.md

@@ -7,10 +7,18 @@ However, there are some cases where you need to use [`findOneAndUpdate()`](https
 * [Atomic Updates](#atomic-updates)
 * [Upsert](#upsert)
 * [The `includeResultMetadata` Option](#includeresultmetadata)
+* [Updating Discriminator Keys](#updating-discriminator-keys)
 
 ## Getting Started
 
-As the name implies, `findOneAndUpdate()` finds the first document that matches a given `filter`, applies an `update`, and returns the document. By default, `findOneAndUpdate()` returns the document as it was **before** `update` was applied.
+As the name implies, `findOneAndUpdate()` finds the first document that matches a given `filter`, applies an `update`, and returns the document.
+The `findOneAndUpdate()` function has the following signature:
+
+```javascript
+function findOneAndUpdate(filter, update, options) {}
+```
+
+By default, `findOneAndUpdate()` returns the document as it was **before** `update` was applied.
 
 ```acquit
 [require:Tutorial.*findOneAndUpdate.*basic case]
@@ -78,3 +86,31 @@ Here's what the `res` object from the above example looks like:
      age: 29 },
   ok: 1 }
 ```
+
+## Updating Discriminator Keys
+
+Mongoose prevents updating the [discriminator key](../discriminators.html#discriminator-keys) using `findOneAndUpdate()` by default.
+For example, suppose you have the following discriminator models.
+
+```javascript
+const eventSchema = new mongoose.Schema({ time: Date });
+const Event = db.model('Event', eventSchema);
+
+const ClickedLinkEvent = Event.discriminator(
+  'ClickedLink',
+  new mongoose.Schema({ url: String })
+);
+
+const SignedUpEvent = Event.discriminator(
+  'SignedUp',
+  new mongoose.Schema({ username: String })
+);
+```
+
+Mongoose will remove `__t` (the default discriminator key) from the `update` parameter, if `__t` is set.
+This is to prevent unintentional updates to the discriminator key; for example, if you're passing untrusted user input to the `update` parameter.
+However, you can tell Mongoose to allow updating the discriminator key by setting the `overwriteDiscriminatorKey` option to `true` as shown below.
+
+```acquit
+[require:use overwriteDiscriminatorKey to change discriminator key]
+```

lib/aggregate.js

@@ -1019,8 +1019,8 @@ Aggregate.prototype.exec = async function exec() {
   const model = this._model;
   const collection = this._model.collection;
 
-  applyGlobalMaxTimeMS(this.options, model);
-  applyGlobalDiskUse(this.options, model);
+  applyGlobalMaxTimeMS(this.options, model.db.options, model.base.options);
+  applyGlobalDiskUse(this.options, model.db.options, model.base.options);
 
   if (this.options && this.options.cursor) {
     return new AggregationCursor(this);

lib/connection.js

@@ -443,6 +443,28 @@ Connection.prototype.createCollections = async function createCollections(option
   return result;
 };
 
+/**
+ * A convenience wrapper for `connection.client.withSession()`.
+ *
+ * #### Example:
+ *
+ *     await conn.withSession(async session => {
+ *       const doc = await TestModel.findOne().session(session);
+ *     });
+ *
+ * @method withSession
+ * @param {Function} executor called with 1 argument: a `ClientSession` instance
+ * @return {Promise} resolves to the return value of the executor function
+ * @api public
+ */
+
+Connection.prototype.withSession = async function withSession(executor) {
+  if (arguments.length === 0) {
+    throw new Error('Please provide an executor function');
+  }
+  return await this.client.withSession(executor);
+};
+
 /**
  * _Requires MongoDB >= 3.6.0._ Starts a [MongoDB session](https://www.mongodb.com/docs/manual/release-notes/3.6/#client-sessions)
  * for benefits like causal consistency, [retryable writes](https://www.mongodb.com/docs/manual/core/retryable-writes/),
@@ -807,6 +829,30 @@ Connection.prototype.openUri = async function openUri(uri, options) {
   return this;
 };
 
+/*!
+ * Treat `on('error')` handlers as handling the initialConnection promise
+ * to avoid uncaught exceptions when using `on('error')`. See gh-14377.
+ */
+
+Connection.prototype.on = function on(event, callback) {
+  if (event === 'error' && this.$initialConnection) {
+    this.$initialConnection.catch(() => {});
+  }
+  return EventEmitter.prototype.on.call(this, event, callback);
+};
+
+/*!
+ * Treat `once('error')` handlers as handling the initialConnection promise
+ * to avoid uncaught exceptions when using `on('error')`. See gh-14377.
+ */
+
+Connection.prototype.once = function on(event, callback) {
+  if (event === 'error' && this.$initialConnection) {
+    this.$initialConnection.catch(() => {});
+  }
+  return EventEmitter.prototype.once.call(this, event, callback);
+};
+
 /*!
  * ignore
  */

lib/constants.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/*!
+ * ignore
+ */
+
+const queryOperations = Object.freeze([
+  // Read
+  'countDocuments',
+  'distinct',
+  'estimatedDocumentCount',
+  'find',
+  'findOne',
+  // Update
+  'findOneAndReplace',
+  'findOneAndUpdate',
+  'replaceOne',
+  'updateMany',
+  'updateOne',
+  // Delete
+  'deleteMany',
+  'deleteOne',
+  'findOneAndDelete'
+]);
+
+exports.queryOperations = queryOperations;
+
+/*!
+ * ignore
+ */
+
+const queryMiddlewareFunctions = queryOperations.concat([
+  'validate'
+]);
+
+exports.queryMiddlewareFunctions = queryMiddlewareFunctions;

lib/cursor/aggregationCursor.js

@@ -57,12 +57,20 @@ util.inherits(AggregationCursor, Readable);
 function _init(model, c, agg) {
   if (!model.collection.buffer) {
     model.hooks.execPre('aggregate', agg, function() {
+      if (typeof agg.options?.cursor?.transform === 'function') {
+        c._transforms.push(agg.options.cursor.transform);
+      }
+
       c.cursor = model.collection.aggregate(agg._pipeline, agg.options || {});
       c.emit('cursor', c.cursor);
     });
   } else {
     model.collection.emitter.once('queue', function() {
       model.hooks.execPre('aggregate', agg, function() {
+        if (typeof agg.options?.cursor?.transform === 'function') {
+          c._transforms.push(agg.options.cursor.transform);
+        }
+
         c.cursor = model.collection.aggregate(agg._pipeline, agg.options || {});
         c.emit('cursor', c.cursor);
       });