mongoose 9.1.6 → 9.2.1

package/lib/model.js

@@ -50,6 +50,7 @@ const immediate = require('./helpers/immediate');
 const internalToObjectOptions = require('./options').internalToObjectOptions;
 const isDefaultIdIndex = require('./helpers/indexes/isDefaultIdIndex');
 const isIndexEqual = require('./helpers/indexes/isIndexEqual');
+const isIndexSpecEqual = require('./helpers/indexes/isIndexSpecEqual');
 const isTimeseriesIndex = require('./helpers/indexes/isTimeseriesIndex');
 const {
   getRelatedDBIndexes,
@@ -63,6 +64,7 @@ const prepareDiscriminatorPipeline = require('./helpers/aggregate/prepareDiscrim
 const pushNestedArrayPaths = require('./helpers/model/pushNestedArrayPaths');
 const removeDeselectedForeignField = require('./helpers/populate/removeDeselectedForeignField');
 const setDottedPath = require('./helpers/path/setDottedPath');
+const { buildMiddlewareFilter } = require('./helpers/buildMiddlewareFilter');
 const util = require('util');
 const utils = require('./utils');
 const minimize = require('./helpers/minimize');
@@ -366,9 +368,9 @@ function _createSaveOptions(doc, options) {
 
 Model.prototype.$__save = async function $__save(options) {
   try {
-    await this._execDocumentPreHooks('save', options);
+    await this._execDocumentPreHooks('save', options, [options]);
   } catch (error) {
-    await this._execDocumentPostHooks('save', error);
+    await this._execDocumentPostHooks('save', options, error);
     return;
   }
 
@@ -466,7 +468,7 @@ Model.prototype.$__save = async function $__save(options) {
     }
   } catch (err) {
     const error = this.$__schema._transformDuplicateKeyError(err);
-    await this._execDocumentPostHooks('save', error);
+    await this._execDocumentPostHooks('save', options, error);
     return;
   }
 
@@ -501,7 +503,7 @@ Model.prototype.$__save = async function $__save(options) {
         this.$__undoReset();
         const err = this.$__.$versionError ||
           new VersionError(this, version, this.$__.modifiedPaths);
-        await this._execDocumentPostHooks('save', err);
+        await this._execDocumentPostHooks('save', options, err);
         return;
       }
 
@@ -513,7 +515,7 @@ Model.prototype.$__save = async function $__save(options) {
     if (result != null && numAffected <= 0) {
       this.$__undoReset();
       const error = new DocumentNotFoundError(where, this.constructor.modelName, numAffected, result);
-      await this._execDocumentPostHooks('save', error);
+      await this._execDocumentPostHooks('save', options, error);
       return;
     }
   }
@@ -521,7 +523,7 @@ Model.prototype.$__save = async function $__save(options) {
   this.$__.savedState = {};
   this.$emit('save', this, numAffected);
   this.constructor.emit('save', this, numAffected);
-  await this._execDocumentPostHooks('save');
+  await this._execDocumentPostHooks('save', options);
 };
 
 /*!
@@ -565,6 +567,9 @@ function generateVersionError(doc, modifiedPaths, defaultPaths) {
  * @param {Boolean} [options.checkKeys=true] the MongoDB driver prevents you from saving keys that start with '$' or contain '.' by default. Set this option to `false` to skip that check. See [restrictions on field names](https://docs.mongodb.com/manual/reference/limits/#mongodb-limit-Restrictions-on-Field-Names)
  * @param {Boolean} [options.timestamps=true] if `false` and [timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this `save()`.
  * @param {Array} [options.pathsToSave] An array of paths that tell mongoose to only validate and save the paths in `pathsToSave`.
+ * @param {Boolean|Object} [options.middleware=true] set to `false` to skip all user-defined middleware
+ * @param {Boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
+ * @param {Boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @throws {DocumentNotFoundError} if this [save updates an existing document](https://mongoosejs.com/docs/api/document.html#Document.prototype.isNew) but the document doesn't exist in the database. For example, you will get this error if the document is [deleted between when you retrieved the document and when you saved it](documents.html#updating).
  * @return {Promise}
  * @api public
@@ -762,8 +767,11 @@ Model.prototype.deleteOne = function deleteOne(options) {
     }
   }
 
+  const preFilter = buildMiddlewareFilter(options, 'pre');
+  const postFilter = buildMiddlewareFilter(options, 'post');
+
   query.pre(async function queryPreDeleteOne() {
-    const res = await self.constructor._middleware.execPre('deleteOne', self, [self, options]);
+    const res = await self.constructor._middleware.execPre('deleteOne', self, [self, options], { filter: preFilter });
     // `self` is passed to pre hooks as argument for backwards compatibility, but that
     // isn't the actual arguments passed to the wrapped function.
     if (res[0] !== self || res[1] !== options) {
@@ -778,7 +786,7 @@ Model.prototype.deleteOne = function deleteOne(options) {
     return res;
   });
   query.pre(function callSubdocPreHooks() {
-    return Promise.all(self.$getAllSubdocs().map(subdoc => subdoc.constructor._middleware.execPre('deleteOne', subdoc, [subdoc])));
+    return Promise.all(self.$getAllSubdocs().map(subdoc => subdoc.constructor._middleware.execPre('deleteOne', subdoc, [subdoc], { filter: preFilter })));
   });
   query.pre(function skipIfAlreadyDeleted() {
     if (self.$__.isDeleted) {
@@ -786,10 +794,10 @@ Model.prototype.deleteOne = function deleteOne(options) {
     }
   });
   query.post(function callSubdocPostHooks() {
-    return Promise.all(self.$getAllSubdocs().map(subdoc => subdoc.constructor._middleware.execPost('deleteOne', subdoc, [subdoc])));
+    return Promise.all(self.$getAllSubdocs().map(subdoc => subdoc.constructor._middleware.execPost('deleteOne', subdoc, [subdoc], { filter: postFilter })));
   });
   query.post(function queryPostDeleteOne() {
-    return self.constructor._middleware.execPost('deleteOne', self, [self], {});
+    return self.constructor._middleware.execPost('deleteOne', self, [self], { filter: postFilter });
   });
   query.transform(function setIsDeleted(result) {
     if (result?.deletedCount > 0) {
@@ -1146,7 +1154,16 @@ Model.createCollection = async function createCollection(options) {
     throw new MongooseError('Model.createCollection() no longer accepts a callback');
   }
 
-  [options] = await this.hooks.execPre('createCollection', this, [options]).catch(err => {
+  const preFilter = buildMiddlewareFilter(options, 'pre');
+  const postFilter = buildMiddlewareFilter(options, 'post');
+
+  // Remove middleware option before passing to MongoDB
+  if (options?.middleware != null) {
+    options = { ...options };
+    delete options.middleware;
+  }
+
+  [options] = await this.hooks.execPre('createCollection', this, [options], { filter: preFilter }).catch(err => {
     if (err instanceof Kareem.skipWrappedFunction) {
       return [err];
     }
@@ -1196,11 +1213,11 @@ Model.createCollection = async function createCollection(options) {
     }
   } catch (err) {
     if (err != null && (err.name !== 'MongoServerError' || err.code !== 48)) {
-      await this.hooks.execPost('createCollection', this, [null], { error: err });
+      await this.hooks.execPost('createCollection', this, [null], { error: err, filter: postFilter });
     }
   }
 
-  await this.hooks.execPost('createCollection', this, [this.$__collection]);
+  await this.hooks.execPost('createCollection', this, [this.$__collection], { filter: postFilter });
 
   return this.$__collection;
 };
@@ -1629,6 +1646,25 @@ function _ensureIndexes(model, options, callback) {
     }
   }
 
+  // Check for duplicate index definitions (gh-15056)
+  const seenIndexes = [];
+  for (const index of indexes) {
+    const fields = index[0];
+    const indexOptions = index[1];
+    if (indexOptions.name == null) {
+      for (const existingIndex of seenIndexes) {
+        if (existingIndex[1].name == null && isIndexSpecEqual(existingIndex[0], fields)) {
+          utils.warn('mongoose: Duplicate schema index on ' + JSON.stringify(fields) +
+            ' for model "' + model.modelName + '". ' +
+            'This is often due to declaring an index using both "index: true" and "schema.index()". ' +
+            'Please remove the duplicate index definition.');
+          break;
+        }
+      }
+    }
+    seenIndexes.push(index);
+  }
+
   if (!indexes.length) {
     immediate(function() {
       done();
@@ -2296,10 +2332,10 @@ Model.$where = function $where() {
  * @param {Object} [conditions]
  * @param {Object} [update]
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {String} [options.returnDocument='before'] Has two possible values, `'before'` and `'after'`. By default, it will return the document before the update was applied.
+ * @param {'before'|'after'} [options.returnDocument='before'] Has two possible values, `'before'` and `'after'`. By default, it will return the document before the update was applied.
  * @param {Object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.lean()) and [the Mongoose lean tutorial](https://mongoosejs.com/docs/tutorials/lean.html).
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](https://mongoosejs.com/docs/transactions.html).
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
  * @param {Boolean} [options.upsert=false] if true, and no documents found, insert a new document
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.select())
@@ -2385,10 +2421,10 @@ Model.findOneAndUpdate = function(conditions, update, options) {
  * @param {Object|Number|String} id value of `_id` to query by
  * @param {Object} [update]
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {String} [options.returnDocument='before'] Has two possible values, `'before'` and `'after'`. By default, it will return the document before the update was applied.
+ * @param {'before'|'after'} [options.returnDocument='before'] Has two possible values, `'before'` and `'after'`. By default, it will return the document before the update was applied.
  * @param {Object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.lean()) and [the Mongoose lean tutorial](https://mongoosejs.com/docs/tutorials/lean.html).
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](https://mongoosejs.com/docs/transactions.html).
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
  * @param {Boolean} [options.runValidators] if true, runs [update validators](https://mongoosejs.com/docs/validation.html#update-validators) on this command. Update validators validate the update operation against the model's schema
@@ -2446,7 +2482,7 @@ Model.findByIdAndUpdate = function(id, update, options) {
  *
  * @param {Object} conditions
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.select())
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](https://mongoosejs.com/docs/transactions.html).
  * @param {Boolean} [options.includeResultMetadata] if true, returns the full [ModifyResult from the MongoDB driver](https://mongodb.github.io/node-mongodb-native/4.9/interfaces/ModifyResult.html) rather than just the document
@@ -2488,7 +2524,7 @@ Model.findOneAndDelete = function(conditions, options) {
  *
  * @param {Object|Number|String} id value of `_id` to query by
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.translateAliases=null] If set to `true`, translates any schema-defined aliases in `filter`, `projection`, `update`, and `distinct`. Throws an error if there are any conflicts where both alias and raw property are defined on the same object.
  * @return {Query}
  * @see Model.findOneAndDelete https://mongoosejs.com/docs/api/model.html#Model.findOneAndDelete()
@@ -2523,10 +2559,10 @@ Model.findByIdAndDelete = function(id, options) {
  * @param {Object} filter Replace the first document that matches this filter
  * @param {Object} [replacement] Replace with this document
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {String} [options.returnDocument='before'] Has two possible values, `'before'` and `'after'`. By default, it will return the document before the update was applied.
+ * @param {'before'|'after'} [options.returnDocument='before'] Has two possible values, `'before'` and `'after'`. By default, it will return the document before the update was applied.
  * @param {Object} [options.lean] if truthy, mongoose will return the document as a plain JavaScript object rather than a mongoose document. See [`Query.lean()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.lean()) and [the Mongoose lean tutorial](https://mongoosejs.com/docs/tutorials/lean.html).
  * @param {ClientSession} [options.session=null] The session associated with this query. See [transactions docs](https://mongoosejs.com/docs/transactions.html).
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
  * @param {Object|String|String[]} [options.projection=null] optional fields to return, see [`Query.prototype.select()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.select())
  * @param {Object|String} [options.sort] if multiple docs are found by the conditions, sets the sort order to choose which doc to update.
@@ -2910,6 +2946,9 @@ Model.startSession = function() {
  * @param {Number} [options.limit=null] this limits the number of documents being processed (validation/casting) by mongoose in parallel, this does **NOT** send the documents in batches to MongoDB. Use this option if you're processing a large number of documents and your app is running out of memory.
  * @param {String|Object|Array} [options.populate=null] populates the result documents. This option is a no-op if `rawResult` is set.
  * @param {Boolean} [options.throwOnValidationError=false] If true and `ordered: false`, throw an error if one of the operations failed validation, but all valid operations completed successfully.
+ * @param {Boolean|Object} [options.middleware=true] set to `false` to skip all user-defined middleware
+ * @param {Boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
+ * @param {Boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @return {Promise} resolving to the raw result from the MongoDB driver if `options.rawResult` was `true`, or the documents that passed validation, otherwise
  * @api public
  */
@@ -2921,13 +2960,15 @@ Model.insertMany = async function insertMany(arr, options) {
     throw new MongooseError('Model.insertMany() no longer accepts a callback');
   }
 
+  options = options || {};
+  const preFilter = buildMiddlewareFilter(options, 'pre');
+  const postFilter = buildMiddlewareFilter(options, 'post');
+
   try {
-    [arr] = await this._middleware.execPre('insertMany', this, [arr]);
+    [arr] = await this._middleware.execPre('insertMany', this, [arr], { filter: preFilter });
   } catch (error) {
-    await this._middleware.execPost('insertMany', this, [arr], { error });
+    await this._middleware.execPost('insertMany', this, [arr], { error, filter: postFilter });
   }
-
-  options = options || {};
   const ThisModel = this;
   const limit = options.limit || 1000;
   const rawResult = !!options.rawResult;
@@ -3104,7 +3145,7 @@ Model.insertMany = async function insertMany(arr, options) {
       decorateBulkWriteResult(error, validationErrors, results);
     }
 
-    await this._middleware.execPost('insertMany', this, [arr], { error });
+    await this._middleware.execPost('insertMany', this, [arr], { error, filter: postFilter });
   }
 
   if (!lean) {
@@ -3152,7 +3193,8 @@ Model.insertMany = async function insertMany(arr, options) {
     });
   }
 
-  return await this._middleware.execPost('insertMany', this, [docAttributes]).then(res => res[0]);
+  const [result] = await this._middleware.execPost('insertMany', this, [docAttributes], { filter: postFilter });
+  return result;
 };
 
 /*!
@@ -3267,6 +3309,9 @@ function _setIsNew(doc, val) {
  * @param {Boolean} [options.bypassDocumentValidation=false] If true, disable [MongoDB server-side schema validation](https://www.mongodb.com/docs/manual/core/schema-validation/) for all writes in this bulk.
  * @param {Boolean} [options.throwOnValidationError=false] If true and `ordered: false`, throw an error if one of the operations failed validation, but all valid operations completed successfully. Note that Mongoose will still send all valid operations to the MongoDB server.
  * @param {Boolean|"throw"} [options.strict=null] Overwrites the [`strict` option](https://mongoosejs.com/docs/guide.html#strict) on schema. If false, allows filtering and writing fields not defined in the schema for all writes in this bulk.
+ * @param {Boolean|Object} [options.middleware=true] set to `false` to skip all user-defined middleware
+ * @param {Boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
+ * @param {Boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @return {Promise} resolves to a [`BulkWriteOpResult`](https://mongodb.github.io/node-mongodb-native/4.9/classes/BulkWriteResult.html) if the operation succeeds
  * @api public
  */
@@ -3279,14 +3324,16 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
     throw new MongooseError('Model.bulkWrite() no longer accepts a callback');
   }
   options = options || {};
+  const preFilter = buildMiddlewareFilter(options, 'pre');
+  const postFilter = buildMiddlewareFilter(options, 'post');
 
   try {
-    [ops, options] = await this.hooks.execPre('bulkWrite', this, [ops, options]);
+    [ops, options] = await this.hooks.execPre('bulkWrite', this, [ops, options], { filter: preFilter });
   } catch (err) {
     if (err instanceof Kareem.skipWrappedFunction) {
       ops = err;
     } else {
-      await this.hooks.execPost('bulkWrite', this, [null], { error: err });
+      await this.hooks.execPost('bulkWrite', this, [null], { error: err, filter: postFilter });
     }
   }
 
@@ -3325,7 +3372,7 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
     try {
       res = await this.$__collection.bulkWrite(ops, options);
     } catch (error) {
-      await this.hooks.execPost('bulkWrite', this, [null], { error });
+      await this.hooks.execPost('bulkWrite', this, [null], { error, filter: postFilter });
     }
   } else {
     let validOpIndexes = [];
@@ -3394,7 +3441,7 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
         decorateBulkWriteResult(error, validationErrors, results);
       }
 
-      await this.hooks.execPost('bulkWrite', this, [null], { error });
+      await this.hooks.execPost('bulkWrite', this, [null], { error, filter: postFilter });
     }
 
     if (validationErrors.length > 0) {
@@ -3411,7 +3458,7 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
     }
   }
 
-  await this.hooks.execPost('bulkWrite', this, [res]);
+  await this.hooks.execPost('bulkWrite', this, [res], { filter: postFilter });
 
   return res;
 };
@@ -3438,6 +3485,9 @@ Model.bulkWrite = async function bulkWrite(ops, options) {
  * @param {number} [options.wtimeout=null] The [write concern timeout](https://www.mongodb.com/docs/manual/reference/write-concern/#wtimeout).
  * @param {Boolean} [options.j=true] If false, disable [journal acknowledgement](https://www.mongodb.com/docs/manual/reference/write-concern/#j-option)
  * @param {Boolean} [options.validateBeforeSave=true] set to `false` to skip Mongoose validation on all documents
+ * @param {Boolean|Object} [options.middleware=true] set to `false` to skip all user-defined middleware
+ * @param {Boolean} [options.middleware.pre=true] set to `false` to skip only pre hooks
+ * @param {Boolean} [options.middleware.post=true] set to `false` to skip only post hooks
  * @return {BulkWriteResult} the return value from `bulkWrite()`
  */
 Model.bulkSave = async function bulkSave(documents, options) {
@@ -3492,7 +3542,7 @@ Model.bulkSave = async function bulkSave(documents, options) {
       successfulDocuments.push(document);
     }
   }
-  await Promise.all(successfulDocuments.map(document => handleSuccessfulWrite(document)));
+  await Promise.all(successfulDocuments.map(document => handleSuccessfulWrite(document, options)));
 
   if (bulkWriteError != null) {
     throw bulkWriteError;
@@ -3502,20 +3552,22 @@ Model.bulkSave = async function bulkSave(documents, options) {
 };
 
 async function buildPreSavePromise(document, options) {
-  const [newOptions] = await document.schema.s.hooks.execPre('save', document, [options]);
+  const preFilter = buildMiddlewareFilter(options, 'pre');
+  const [newOptions] = await document.schema.s.hooks.execPre('save', document, [options], { filter: preFilter });
   if (newOptions !== options) {
     throw new Error('Cannot overwrite options in pre("save") hook on bulkSave()');
   }
 }
 
-async function handleSuccessfulWrite(document) {
+async function handleSuccessfulWrite(document, options) {
   if (document.$isNew) {
     _setIsNew(document, false);
   }
 
   document.$__reset();
   document._applyVersionIncrement();
-  return document.schema.s.hooks.execPost('save', document, [document]);
+  const postFilter = buildMiddlewareFilter(options, 'post');
+  return document.schema.s.hooks.execPost('save', document, [document], { filter: postFilter });
 }
 
 /**
@@ -3824,7 +3876,7 @@ Model.buildBulkWriteOperations = function buildBulkWriteOperations(documents, op
  * @param {Boolean} [options.setters=false] if true, apply schema setters when hydrating
  * @param {Boolean} [options.hydratedPopulatedDocs=false] if true, populates the docs if passing pre-populated data
  * @param {Boolean} [options.virtuals=false] if true, sets any virtuals present on `obj`
- * @param {Boolean|String} [options.strict=false] configure strict mode for the hydrated document. In particular, if strict is false, fields not in the schema won't be stripped out; if strict is 'throw', `hydrate()` will throw an error if there are any fields that are not in the schema. Defaults to true (silently strip out fields not in the schema).
+ * @param {Boolean|'throw'} [options.strict=false] configure strict mode for the hydrated document. In particular, if strict is false, fields not in the schema won't be stripped out; if strict is 'throw', `hydrate()` will throw an error if there are any fields that are not in the schema. Defaults to true (silently strip out fields not in the schema).
  * @return {Document} document instance
  * @api public
  */
@@ -3875,7 +3927,7 @@ Model.hydrate = function(obj, projection, options) {
  * @param {Object} filter
  * @param {Object|Array} update. If array, this update will be treated as an update pipeline and not casted.
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.upsert=false] if true, and no documents found, insert a new document
  * @param {Object} [options.writeConcern=null] sets the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern/) for replica sets. Overrides the [schema-level write concern](https://mongoosejs.com/docs/guide.html#writeConcern)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Does nothing if schema-level timestamps are not set.
@@ -3923,7 +3975,7 @@ Model.updateMany = function updateMany(conditions, update, options) {
  * @param {Object} filter
  * @param {Object|Array} update. If array, this update will be treated as an update pipeline and not casted.
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.upsert=false] if true, and no documents found, insert a new document
  * @param {Object} [options.writeConcern=null] sets the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern/) for replica sets. Overrides the [schema-level write concern](https://mongoosejs.com/docs/guide.html#writeConcern)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Note that this allows you to overwrite timestamps. Does nothing if schema-level timestamps are not set.
@@ -3961,7 +4013,7 @@ Model.updateOne = function updateOne(conditions, doc, options) {
  * @param {Object} filter
  * @param {Object} doc
  * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @param {Boolean|String} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
+ * @param {Boolean|'throw'} [options.strict] overwrites the schema's [strict mode option](https://mongoosejs.com/docs/guide.html#strict)
  * @param {Boolean} [options.upsert=false] if true, and no documents found, insert a new document
  * @param {Object} [options.writeConcern=null] sets the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern/) for replica sets. Overrides the [schema-level write concern](https://mongoosejs.com/docs/guide.html#writeConcern)
  * @param {Boolean} [options.timestamps=null] If set to `false` and [schema-level timestamps](https://mongoosejs.com/docs/guide.html#timestamps) are enabled, skip timestamps for this update. Does nothing if schema-level timestamps are not set.
@@ -4002,7 +4054,7 @@ function _update(model, op, conditions, doc, options) {
   }
   options = typeof options === 'function' ? options : clone(options);
 
-  const versionKey = model?.schema?.options?.versionKey || null;
+  const versionKey = model?.schema?.options?.versionKey ?? null;
   decorateUpdateWithVersionKey(doc, options, versionKey);
 
   return mq[op](conditions, doc, options);

package/lib/mongoose.js

@@ -233,7 +233,8 @@ Mongoose.prototype.setDriver = function setDriver(driver) {
  * - `maxTimeMS`: If set, attaches [maxTimeMS](https://www.mongodb.com/docs/manual/reference/operator/meta/maxTimeMS/) to every query
  * - `objectIdGetter`: `true` by default. Mongoose adds a getter to MongoDB ObjectId's called `_id` that returns `this` for convenience with populate. Set this to false to remove the getter.
  * - `overwriteModels`: Set to `true` to default to overwriting models with the same name when calling `mongoose.model()`, as opposed to throwing an `OverwriteModelError`.
- * - `returnOriginal`: If `false`, changes the default `returnOriginal` option to `findOneAndUpdate()`, `findByIdAndUpdate`, and `findOneAndReplace()` to false. This is equivalent to setting the `new` option to `true` for `findOneAndX()` calls by default. Read our [`findOneAndUpdate()` tutorial](https://mongoosejs.com/docs/tutorials/findoneandupdate.html) for more information.
+ * - `returnDocument`: Set to `'before'` or `'after'` to set the default value for the `returnDocument` option to `findOneAndUpdate()`, `findByIdAndUpdate()`, and `findOneAndReplace()`. Defaults to `'before'`, which returns the document before the update was applied. Read our [`findOneAndUpdate()` tutorial](https://mongoosejs.com/docs/tutorials/findoneandupdate.html) for more information.
+ * - `returnOriginal`: **Deprecated.** Use `returnDocument` instead. If `false`, changes the default `returnOriginal` option to `findOneAndUpdate()`, `findByIdAndUpdate`, and `findOneAndReplace()` to false. This is equivalent to setting the `new` option to `true` for `findOneAndX()` calls by default. Read our [`findOneAndUpdate()` tutorial](https://mongoosejs.com/docs/tutorials/findoneandupdate.html) for more information.
  * - `runValidators`: `false` by default. Set to true to enable [update validators](https://mongoosejs.com/docs/validation.html#update-validators) for all validators by default.
  * - `sanitizeFilter`: `false` by default. Set to true to enable the [sanitization of the query filters](https://mongoosejs.com/docs/api/mongoose.html#Mongoose.prototype.sanitizeFilter()) against query selector injection attacks by wrapping any nested objects that have a property whose name starts with `$` in a `$eq`.
  * - `selectPopulatedPaths`: `true` by default. Set to false to opt out of Mongoose adding all fields that you `populate()` to your `select()`. The schema-level option `selectPopulatedPaths` overwrites this one.
@@ -242,6 +243,8 @@ Mongoose.prototype.setDriver = function setDriver(driver) {
  * - `timestamps.createdAt.immutable`: `true` by default. If `false`, it will change the `createdAt` field to be [`immutable: false`](https://mongoosejs.com/docs/api/schematype.html#SchemaType.prototype.immutable) which means you can update the `createdAt`
  * - `toJSON`: `{ transform: true, flattenDecimals: true }` by default. Overwrites default objects to [`toJSON()`](https://mongoosejs.com/docs/api/document.html#Document.prototype.toJSON()), for determining how Mongoose documents get serialized by `JSON.stringify()`
  * - `toObject`: `{ transform: true, flattenDecimals: true }` by default. Overwrites default objects to [`toObject()`](https://mongoosejs.com/docs/api/document.html#Document.prototype.toObject())
+ * - `transactionAsyncLocalStorage`: `false` by default. If `true`, Mongoose will automatically pass the `session` to any operation executing within a transaction executor function. See [transaction AsyncLocalStorage documentation](https://mongoosejs.com/docs/transactions.html#asynclocalstorage)
+ * - `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
@@ -313,6 +316,23 @@ Mongoose.prototype.set = function getsetOptions(key, value) {
           _mongoose.connections.shift();
         }
       }
+    } else if (optionKey === 'returnOriginal') {
+      if (_mongoose.options.returnDocument != null) {
+        throw new MongooseError(
+          'Cannot set `returnOriginal` when `returnDocument` is already set. Use `returnDocument` instead.'
+        );
+      }
+      const replacement = optionValue === true ? '\'before\'' : '\'after\'';
+      utils.warn(
+        'Mongoose: the `returnOriginal` option for `mongoose.set()` is deprecated. ' +
+        'Use `mongoose.set(\'returnDocument\', ' + replacement + ')` instead.'
+      );
+    } else if (optionKey === 'returnDocument') {
+      if (_mongoose.options.returnOriginal != null) {
+        throw new MongooseError(
+          'Cannot set `returnDocument` when `returnOriginal` is already set. Use `returnDocument` instead of `returnOriginal`.'
+        );
+      }
     }
   }
 

package/lib/options.js

@@ -13,5 +13,6 @@ exports.internalToObjectOptions = {
   flattenDecimals: false,
   useProjection: false,
   versionKey: true,
-  flattenObjectIds: false
+  flattenObjectIds: false,
+  flattenUUIDs: false
 };

package/lib/plugins/saveSubdocs.js

@@ -1,76 +1,94 @@
 'use strict';
 
+const symbols = require('../schema/symbols');
+
 /*!
  * ignore
  */
 
 module.exports = function saveSubdocs(schema) {
   const unshift = true;
-  schema.s.hooks.pre('save', false, async function saveSubdocsPreSave() {
-    if (this.$isSubdocument) {
-      return;
-    }
-
-    const subdocs = this.$getAllSubdocs({ useCache: true });
-
-    if (!subdocs.length) {
-      return;
-    }
-
-    const options = this.$__.saveOptions;
-    await Promise.all(subdocs.map(subdoc => subdoc._execDocumentPreHooks('save', options)));
-
-    // Invalidate subdocs cache because subdoc pre hooks can add new subdocuments
-    if (this.$__.saveOptions) {
-      this.$__.saveOptions.__subdocs = null;
-    }
-  }, null, unshift);
-
-  schema.s.hooks.pre('save', async function saveSubdocsPreDeleteOne() {
-    const removedSubdocs = this.$__.removedSubdocs;
-    if (!removedSubdocs?.length) {
-      return;
-    }
-
-    const promises = [];
-    for (const subdoc of removedSubdocs) {
-      promises.push(subdoc._execDocumentPreHooks('deleteOne'));
-    }
-
-    await Promise.all(promises);
-  });
-
-  schema.s.hooks.post('save', async function saveSubdocsPostDeleteOne() {
-    const removedSubdocs = this.$__.removedSubdocs;
-    if (!removedSubdocs?.length) {
-      return;
-    }
-
-    const promises = [];
-    for (const subdoc of removedSubdocs) {
-      promises.push(subdoc._execDocumentPostHooks('deleteOne'));
-    }
-
-    this.$__.removedSubdocs = null;
-    await Promise.all(promises);
-  });
-
-  schema.s.hooks.post('save', async function saveSubdocsPostSave() {
-    if (this.$isSubdocument) {
-      return;
-    }
-
-    const subdocs = this.$getAllSubdocs({ useCache: true });
-
-    if (!subdocs.length) {
-      return;
-    }
-
-    const promises = [];
-    for (const subdoc of subdocs) {
-      promises.push(subdoc._execDocumentPostHooks('save'));
-    }
-
-    await Promise.all(promises);
-  }, null, unshift);
+
+  schema.s.hooks.pre('save', false, saveSubdocsPreSave, null, unshift);
+  schema.s.hooks.post('save', saveSubdocsPostSave, null, unshift);
+  schema.s.hooks.pre('save', saveSubdocsPreDeleteOne);
+  schema.s.hooks.post('save', saveSubdocsPostDeleteOne);
 };
+
+
+async function saveSubdocsPreSave() {
+  if (this.$isSubdocument) {
+    return;
+  }
+
+  const subdocs = this.$getAllSubdocs({ useCache: true });
+
+  if (!subdocs.length) {
+    return;
+  }
+
+  const options = this.$__.saveOptions;
+  await Promise.all(subdocs.map(subdoc => subdoc._execDocumentPreHooks('save', options, [options])));
+
+  // Invalidate subdocs cache because subdoc pre hooks can add new subdocuments
+  if (this.$__.saveOptions) {
+    this.$__.saveOptions.__subdocs = null;
+  }
+}
+
+async function saveSubdocsPostSave() {
+  if (this.$isSubdocument) {
+    return;
+  }
+
+  const subdocs = this.$getAllSubdocs({ useCache: true });
+
+  if (!subdocs.length) {
+    return;
+  }
+
+  const options = this.$__.saveOptions;
+  const promises = [];
+  for (const subdoc of subdocs) {
+    promises.push(subdoc._execDocumentPostHooks('save', options));
+  }
+
+  await Promise.all(promises);
+}
+
+async function saveSubdocsPreDeleteOne() {
+  const removedSubdocs = this.$__.removedSubdocs;
+  if (!removedSubdocs?.length) {
+    return;
+  }
+
+  const options = this.$__.saveOptions;
+  const promises = [];
+  for (const subdoc of removedSubdocs) {
+    promises.push(subdoc._execDocumentPreHooks('deleteOne', options));
+  }
+
+  await Promise.all(promises);
+}
+
+async function saveSubdocsPostDeleteOne() {
+  const removedSubdocs = this.$__.removedSubdocs;
+  if (!removedSubdocs?.length) {
+    return;
+  }
+
+  const options = this.$__.saveOptions;
+  const promises = [];
+  for (const subdoc of removedSubdocs) {
+    promises.push(subdoc._execDocumentPostHooks('deleteOne', options));
+  }
+
+  this.$__.removedSubdocs = null;
+  await Promise.all(promises);
+}
+
+
+saveSubdocsPreSave[symbols.builtInMiddleware] = true;
+saveSubdocsPostSave[symbols.builtInMiddleware] = true;
+saveSubdocsPreDeleteOne[symbols.builtInMiddleware] = true;
+saveSubdocsPostDeleteOne[symbols.builtInMiddleware] = true;