@nullix/zod-mongoose-studio 1.0.13 → 2.1.0

package/.output/server/node_modules/mongoose/lib/document.js

@@ -22,6 +22,7 @@ const $__hasIncludedChildren = require('./helpers/projection/hasIncludedChildren
 const applyDefaults = require('./helpers/document/applyDefaults');
 const cleanModifiedSubpaths = require('./helpers/document/cleanModifiedSubpaths');
 const clone = require('./helpers/clone');
+const isInPathsToSave = require('./helpers/document/isInPathsToSave');
 const compile = require('./helpers/document/compile').compile;
 const defineKey = require('./helpers/document/compile').defineKey;
 const firstKey = require('./helpers/firstKey');
@@ -30,7 +31,6 @@ const getEmbeddedDiscriminatorPath = require('./helpers/document/getEmbeddedDisc
 const getKeysInSchemaOrder = require('./helpers/schema/getKeysInSchemaOrder');
 const getSubdocumentStrictValue = require('./helpers/schema/getSubdocumentStrictValue');
 const handleSpreadDoc = require('./helpers/document/handleSpreadDoc');
-const immediate = require('./helpers/immediate');
 const isBsonType = require('./helpers/isBsonType');
 const isDefiningProjection = require('./helpers/projection/isDefiningProjection');
 const isExclusive = require('./helpers/projection/isExclusive');
@@ -42,6 +42,7 @@ const minimize = require('./helpers/minimize');
 const mpath = require('mpath');
 const parentPaths = require('./helpers/path/parentPaths');
 const queryhelpers = require('./queryHelpers');
+const { buildMiddlewareFilter } = require('./helpers/buildMiddlewareFilter');
 const utils = require('./utils');
 const isPromise = require('./helpers/isPromise');
 
@@ -63,7 +64,6 @@ const getDeepestSubdocumentForPath = require('./helpers/document/getDeepestSubdo
 const sessionNewDocuments = require('./helpers/symbols').sessionNewDocuments;
 
 let DocumentArray;
-let MongooseArray;
 let Embedded;
 
 const specialProperties = utils.specialProperties;
@@ -76,36 +76,37 @@ const VERSION_ALL = VERSION_WHERE | VERSION_INC;
  * The core Mongoose document constructor. You should not call this directly,
  * the Mongoose [Model constructor](./api/model.html#Model) calls this for you.
  *
- * @param {Object} obj the values to set
- * @param {Object} [fields] optional object containing the fields which were selected in the query returning this document and any populated paths data
- * @param {Object} [options] various configuration options for the document
- * @param {Boolean} [options.defaults=true] if `false`, skip applying default values to this document.
+ * @param {object} obj the values to set
+ * @param {object} [fields] optional object containing the fields which were selected in the query returning this document and any populated paths data
+ * @param {object} [options] various configuration options for the document
+ * @param {boolean} [options.defaults=true] if `false`, skip applying default values to this document.
+ * @param {boolean} [options.skipId=false] By default, Mongoose document if one is not provided and the document's schema does not override Mongoose's default `_id`. Set `skipId` to `true` to skip this generation step.
  * @inherits NodeJS EventEmitter https://nodejs.org/api/events.html#class-eventemitter
  * @event `init`: Emitted on a document after it has been retrieved from the db and fully hydrated by Mongoose.
  * @event `save`: Emitted when the document is successfully saved
  * @api private
  */
 
-function Document(obj, fields, skipId, options) {
-  if (typeof skipId === 'object' && skipId != null) {
-    options = skipId;
-    skipId = options.skipId;
+function Document(obj, fields, options) {
+  if (typeof options === 'boolean') {
+    throw new Error('The skipId parameter has been removed. Use { skipId: true } in the options parameter instead.');
   }
   options = Object.assign({}, options);
+  let skipId = options.skipId;
+
+  this.$__ = new InternalCache();
 
   // Support `browserDocument.js` syntax
   if (this.$__schema == null) {
     const _schema = utils.isObject(fields) && !fields.instanceOfSchema ?
       new Schema(fields) :
       fields;
+
     this.$__setSchema(_schema);
-    fields = skipId;
-    skipId = options;
-    options = arguments[4] || {};
+    fields = options;
+    skipId = options.skipId;
   }
 
-  this.$__ = new InternalCache();
-
   // Avoid setting `isNew` to `true`, because it is `true` by default
   if (options.isNew != null && options.isNew !== true) {
     this.$isNew = options.isNew;
@@ -151,7 +152,7 @@ function Document(obj, fields, skipId, options) {
 
   // determine if this doc is a result of a query with
   // excluded fields
-  if (utils.isPOJO(fields) && Object.keys(fields).length > 0) {
+  if (utils.isPOJO(fields) && utils.hasOwnKeys(fields)) {
     exclude = isExclusive(fields);
     this.$__.selected = fields;
     this.$__.exclude = exclude;
@@ -547,11 +548,11 @@ function $applyDefaultsToNested(val, path, doc) {
 /**
  * Builds the default doc structure
  *
- * @param {Object} obj
- * @param {Object} [fields]
- * @param {Boolean} [skipId]
- * @param {Boolean} [exclude]
- * @param {Object} [hasIncludedChildren]
+ * @param {object} obj
+ * @param {object} [fields]
+ * @param {boolean} [skipId]
+ * @param {boolean} [exclude]
+ * @param {object} [hasIncludedChildren]
  * @api private
  * @method $__buildDoc
  * @memberOf Document
@@ -635,9 +636,9 @@ Document.prototype.toBSON = function() {
  * This function triggers `init` [middleware](https://mongoosejs.com/docs/middleware.html).
  * Note that `init` hooks are [synchronous](https://mongoosejs.com/docs/middleware.html#synchronous).
  *
- * @param {Object} doc raw document returned by mongo
- * @param {Object} [opts]
- * @param {Boolean} [opts.hydratedPopulatedDocs=false] If true, hydrate and mark as populated any paths that are populated in the raw document
+ * @param {object} doc raw document returned by mongo
+ * @param {object} [opts]
+ * @param {boolean} [opts.hydratedPopulatedDocs=false] If true, hydrate and mark as populated any paths that are populated in the raw document
  * @param {Function} [fn]
  * @api public
  * @memberOf Document
@@ -677,12 +678,15 @@ Document.prototype.$init = function() {
  * Internal "init" function
  *
  * @param {Document} doc
- * @param {Object} [opts]
+ * @param {object} [opts]
  * @returns {Document} this
  * @api private
  */
 
 Document.prototype.$__init = function(doc, opts) {
+  if (doc == null) {
+    throw new ObjectParameterError(doc, 'doc', 'init');
+  }
   this.$isNew = false;
   opts = opts || {};
 
@@ -701,7 +705,7 @@ Document.prototype.$__init = function(doc, opts) {
         continue;
       }
       for (const child of item._childDocs) {
-        if (child == null || child.$__ == null) {
+        if (child?.$__ == null) {
           continue;
         }
         child.$__.parent = this;
@@ -727,18 +731,22 @@ Document.prototype.$__init = function(doc, opts) {
 /**
  * Init helper.
  *
- * @param {Object} self document instance
- * @param {Object} obj raw mongodb doc
- * @param {Object} doc object we are initializing
- * @param {Object} [opts] Optional Options
- * @param {Boolean} [opts.setters] Call `applySetters` instead of `cast`
- * @param {String} [prefix] Prefix to add to each path
+ * @param {object} self document instance
+ * @param {object} obj raw mongodb doc
+ * @param {object} doc object we are initializing
+ * @param {object} [opts] Optional Options
+ * @param {boolean} [opts.setters] Call `applySetters` instead of `cast`
+ * @param {string} [prefix] Prefix to add to each path
  * @api private
  */
 
 function init(self, obj, doc, opts, prefix) {
   prefix = prefix || '';
 
+  if (typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new ObjectExpectedError(self.$basePath, obj);
+  }
+
   if (obj.$__ != null) {
     obj = obj._doc;
   }
@@ -802,7 +810,7 @@ function init(self, obj, doc, opts, prefix) {
 
         if (schemaType && !wasPopulated && !opts.hydratedPopulatedDocs) {
           try {
-            if (opts && opts.setters) {
+            if (opts?.setters) {
               // Call applySetters with `init = false` because otherwise setters are a noop
               const overrideInit = false;
               doc[i] = schemaType.applySetters(value, self, overrideInit, null, opts);
@@ -821,7 +829,7 @@ function init(self, obj, doc, opts, prefix) {
         } else if (schemaType && opts.hydratedPopulatedDocs) {
           doc[i] = schemaType.cast(value, self, true, undefined, { hydratedPopulatedDocs: true });
 
-          if (doc[i] && doc[i].$__ && doc[i].$__.wasPopulated) {
+          if (doc[i]?.$__?.wasPopulated) {
             self.$populated(path, doc[i].$__.wasPopulated.value, doc[i].$__.wasPopulated.options);
           } else if (Array.isArray(doc[i]) && doc[i].length && doc[i][0]?.$__?.wasPopulated) {
             self.$populated(path, doc[i].map(populatedDoc => populatedDoc?.$__?.wasPopulated?.value).filter(val => val != null), doc[i][0].$__.wasPopulated.options);
@@ -850,39 +858,47 @@ function init(self, obj, doc, opts, prefix) {
  *  - same as in [Model.updateOne](https://mongoosejs.com/docs/api/model.html#Model.updateOne)
  *
  * @see Model.updateOne https://mongoosejs.com/docs/api/model.html#Model.updateOne
- * @param {Object} update
- * @param {Object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
- * @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 {Boolean|String} [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} update
+ * @param {object} [options] optional see [`Query.prototype.setOptions()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.setOptions())
+ * @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 {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|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 {Query}
  * @api public
  * @memberOf Document
  * @instance
  */
 
-Document.prototype.updateOne = function updateOne(update, options, callback) {
+Document.prototype.updateOne = function updateOne(update, options) {
   const query = this.constructor.updateOne();
   const self = this;
-  query.pre(function queryPreUpdateOne(cb) {
-    self.constructor._middleware.execPre('updateOne', self, [self, update, options], (err, res) => {
-      this.updateOne({ _id: self._doc._id }, update, options);
-      if (self.$session() != null) {
-        if (!('session' in query.options)) {
-          query.options.session = self.$session();
-        }
+  query.pre(async function queryPreUpdateOne() {
+    const res = await self._execDocumentPreHooks('updateOne', options, [self, update, options]);
+    // `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] !== update || res[2] !== options) {
+      throw new Error('Document updateOne pre hooks cannot overwrite arguments');
+    }
+    query.updateOne({ _id: self._doc._id }, update, options);
+    // Apply custom where conditions _after_ document updateOne middleware for
+    // consistency with save() - sharding plugin needs to set $where
+    if (self.$where != null) {
+      this.where(self.$where);
+    }
+    if (self.$session() != null) {
+      if (!('session' in query.options)) {
+        query.options.session = self.$session();
       }
-      return cb(err, res);
-    });
+    }
+    return res;
   });
-  query.post(function queryPostUpdateOne(cb) {
-    self.constructor._middleware.execPost('updateOne', self, [self], {}, cb);
+  query.post(function queryPostUpdateOne() {
+    return self._execDocumentPostHooks('updateOne', options);
   });
 
-  if (callback != null) {
-    return query.exec(callback);
-  }
-
   return query;
 };
 
@@ -894,8 +910,8 @@ Document.prototype.updateOne = function updateOne(update, options, callback) {
  *  - same as in [Model.replaceOne](https://mongoosejs.com/docs/api/model.html#Model.replaceOne())
  *
  * @see Model.replaceOne https://mongoosejs.com/docs/api/model.html#Model.replaceOne()
- * @param {Object} doc
- * @param {Object} [options]
+ * @param {object} doc
+ * @param {object} [options]
  * @param {Function} [callback]
  * @return {Query}
  * @api public
@@ -934,14 +950,14 @@ Document.prototype.replaceOne = function replaceOne() {
 
 Document.prototype.$session = function $session(session) {
   if (arguments.length === 0) {
-    if (this.$__.session != null && this.$__.session.hasEnded) {
+    if (this.$__.session?.hasEnded) {
       this.$__.session = null;
       return null;
     }
     return this.$__.session;
   }
 
-  if (session != null && session.hasEnded) {
+  if (session?.hasEnded) {
     throw new MongooseError('Cannot set a document\'s session to a session that has ended. Make sure you haven\'t ' +
       'called `endSession()` on the session you are passing to `$session()`.');
   }
@@ -976,7 +992,7 @@ Document.prototype.$session = function $session(session) {
  *     doc.$timestamps(false);
  *     await doc.save(); // Does **not** apply timestamps
  *
- * @param {Boolean} [value] overwrite the current session
+ * @param {boolean} [value] overwrite the current session
  * @return {Document|boolean|undefined} When used as a getter (no argument), a boolean will be returned indicating the timestamps option state or if unset "undefined" will be used, otherwise will return "this"
  * @method $timestamps
  * @api public
@@ -1009,7 +1025,7 @@ Document.prototype.$timestamps = function $timestamps(value) {
  * for immutable properties. Behaves similarly to `set()`, except for it
  * unsets all properties that aren't in `obj`.
  *
- * @param {Object} obj the object to overwrite this document with
+ * @param {object} obj the object to overwrite this document with
  * @method overwrite
  * @memberOf Document
  * @instance
@@ -1018,17 +1034,21 @@ Document.prototype.$timestamps = function $timestamps(value) {
  */
 
 Document.prototype.overwrite = function overwrite(obj) {
-  const keys = Array.from(new Set(Object.keys(this._doc).concat(Object.keys(obj))));
+  const keys = new Set(Object.keys(this._doc));
+  for (const key of Object.keys(obj)) {
+    keys.add(key);
+  }
 
+  const schemaOptions = this.$__schema.options;
   for (const key of keys) {
     if (key === '_id') {
       continue;
     }
     // Explicitly skip version key
-    if (this.$__schema.options.versionKey && key === this.$__schema.options.versionKey) {
+    if (schemaOptions.versionKey && key === schemaOptions.versionKey) {
       continue;
     }
-    if (this.$__schema.options.discriminatorKey && key === this.$__schema.options.discriminatorKey) {
+    if (schemaOptions.discriminatorKey && key === schemaOptions.discriminatorKey) {
       continue;
     }
     this.$set(key, obj[key]);
@@ -1040,11 +1060,11 @@ Document.prototype.overwrite = function overwrite(obj) {
 /**
  * Alias for `set()`, used internally to avoid conflicts
  *
- * @param {String|Object} path path or object of key/vals to set
- * @param {Any} val the value to set
- * @param {Schema|String|Number|Buffer|*} [type] optionally specify a type for "on-the-fly" attributes
- * @param {Object} [options] optionally specify options that modify the behavior of the set
- * @param {Boolean} [options.merge=false] if true, setting a [nested path](https://mongoosejs.com/docs/subdocs.html#subdocuments-versus-nested-paths) will merge existing values rather than overwrite the whole object. So `doc.set('nested', { a: 1, b: 2 })` becomes `doc.set('nested.a', 1); doc.set('nested.b', 2);`
+ * @param {string|object} path path or object of key/vals to set
+ * @param {any} val the value to set
+ * @param {Schema|string|number|Buffer|any} [type] optionally specify a type for "on-the-fly" attributes
+ * @param {object} [options] optionally specify options that modify the behavior of the set
+ * @param {boolean} [options.merge=false] if true, setting a [nested path](https://mongoosejs.com/docs/subdocs.html#subdocuments-versus-nested-paths) will merge existing values rather than overwrite the whole object. So `doc.set('nested', { a: 1, b: 2 })` becomes `doc.set('nested.a', 1); doc.set('nested.b', 2);`
  * @return {Document} this
  * @method $set
  * @memberOf Document
@@ -1058,7 +1078,7 @@ Document.prototype.$set = function $set(path, val, type, options) {
     type = undefined;
   }
 
-  const merge = options && options.merge;
+  const merge = options?.merge;
   const adhoc = type && type !== true;
   const constructing = type === true;
   let adhocs;
@@ -1104,7 +1124,7 @@ Document.prototype.$set = function $set(path, val, type, options) {
 
     // `_skipMinimizeTopLevel` is because we may have deleted the top-level
     // nested key to ensure key order.
-    const _skipMinimizeTopLevel = options && options._skipMinimizeTopLevel || false;
+    const _skipMinimizeTopLevel = options?._skipMinimizeTopLevel || false;
     if (len === 0 && _skipMinimizeTopLevel) {
       delete options._skipMinimizeTopLevel;
       if (val) {
@@ -1408,17 +1428,31 @@ Document.prototype.$set = function $set(path, val, type, options) {
       }
 
       // Check refPath
-      const refPath = schema.options.refPath;
+      let refPath = schema.options.refPath;
       if (refPath == null) {
         return false;
       }
-      const modelName = val.get(refPath);
+
+      if (typeof refPath === 'function' && !refPath[modelSymbol]) {
+        let fullPath = path;
+        const fullPathWithIndexes = this.$__fullPathWithIndexes?.();
+        if (fullPathWithIndexes?.length) {
+          fullPath = fullPathWithIndexes + '.' + path;
+        }
+        refPath = refPath.call(this, this, fullPath);
+      }
+
+      if (typeof refPath !== 'string') {
+        throw new MongooseError('`refPath` must be a string or a function that returns a string, got ' + inspect(refPath));
+      }
+
+      const modelName = this.ownerDocument().get(refPath);
       return modelName === model.modelName || modelName === model.baseModelName;
     })();
 
     let didPopulate = false;
     if (refMatches && val instanceof Document && (!val.$__.wasPopulated || utils.deepEqual(val.$__.wasPopulated.value, val._doc._id))) {
-      const unpopulatedValue = (schema && schema.$isSingleNested) ? schema.cast(val, this) : val._doc._id;
+      const unpopulatedValue = schema?.$isSingleNested ? schema.cast(val, this) : val._doc._id;
       this.$populated(path, unpopulatedValue, { [populateModelSymbol]: val.constructor });
       val.$__.wasPopulated = { value: unpopulatedValue };
       didPopulate = true;
@@ -1450,7 +1484,7 @@ Document.prototype.$set = function $set(path, val, type, options) {
       if (this.$__schema.singleNestedPaths[path] != null && parts.length > 1) {
         setterContext = getDeepestSubdocumentForPath(this, parts, this.schema);
       }
-      if (options != null && options.overwriteImmutable) {
+      if (options?.overwriteImmutable) {
         val = schema.applySetters(val, setterContext, false, priorVal, { path, overwriteImmutable: true });
       } else {
         val = schema.applySetters(val, setterContext, false, priorVal, { path });
@@ -1461,9 +1495,7 @@ Document.prototype.$set = function $set(path, val, type, options) {
         !Array.isArray(schema) &&
         schema.$isMongooseDocumentArray &&
         val.length !== 0 &&
-        val[0] != null &&
-        val[0].$__ != null &&
-        val[0].$__.populated != null) {
+        val[0]?.$__?.populated != null) {
       const populatedPaths = Object.keys(val[0].$__.populated);
       for (const populatedPath of populatedPaths) {
         this.$populated(path + '.' + populatedPath,
@@ -1596,10 +1628,10 @@ function _isManuallyPopulatedArray(val, ref) {
  *     // changing strict mode behavior
  *     doc.set(path, value, { strict: false });
  *
- * @param {String|Object} path path or object of key/vals to set
- * @param {Any} val the value to set
- * @param {Schema|String|Number|Buffer|*} [type] optionally specify a type for "on-the-fly" attributes
- * @param {Object} [options] optionally specify options that modify the behavior of the set
+ * @param {string|object} path path or object of key/vals to set
+ * @param {any} val the value to set
+ * @param {Schema|string|number|Buffer|any} [type] optionally specify a type for "on-the-fly" attributes
+ * @param {object} [options] optionally specify options that modify the behavior of the set
  * @return {Document} this
  * @api public
  * @method set
@@ -1613,14 +1645,14 @@ Document.prototype.set = Document.prototype.$set;
  * Determine if we should mark this change as modified.
  *
  * @param {never} pathToMark UNUSED
- * @param {String|Symbol} path
- * @param {Object} options
- * @param {Any} constructing
+ * @param {string|symbol} path
+ * @param {object} options
+ * @param {any} constructing
  * @param {never} parts UNUSED
  * @param {Schema} schema
- * @param {Any} val
- * @param {Any} priorVal
- * @return {Boolean}
+ * @param {any} val
+ * @param {any} priorVal
+ * @return {boolean}
  * @api private
  * @method $__shouldModify
  * @memberOf Document
@@ -1628,7 +1660,7 @@ Document.prototype.set = Document.prototype.$set;
  */
 
 Document.prototype.$__shouldModify = function(pathToMark, path, options, constructing, parts, schema, val, priorVal) {
-  if (options && options._skipMarkModified) {
+  if (options?._skipMarkModified) {
     return false;
   }
   if (this.$isNew) {
@@ -1677,14 +1709,14 @@ Document.prototype.$__shouldModify = function(pathToMark, path, options, constru
 /**
  * Handles the actual setting of the value and marking the path modified if appropriate.
  *
- * @param {String} pathToMark
- * @param {String|Symbol} path
- * @param {Object} options
- * @param {Any} constructing
+ * @param {string} pathToMark
+ * @param {string|symbol} path
+ * @param {object} options
+ * @param {any} constructing
  * @param {Array} parts
  * @param {Schema} schema
- * @param {Any} val
- * @param {Any} priorVal
+ * @param {any} val
+ * @param {any} priorVal
  * @api private
  * @method $__set
  * @memberOf Document
@@ -1694,20 +1726,20 @@ Document.prototype.$__shouldModify = function(pathToMark, path, options, constru
 Document.prototype.$__set = function(pathToMark, path, options, constructing, parts, schema, val, priorVal) {
   Embedded = Embedded || require('./types/arraySubdocument');
 
-  const shouldModify = this.$__shouldModify(pathToMark, path, options, constructing, parts,
-    schema, val, priorVal);
+  const shouldModify = this.$isNew && !options?._skipMarkModified ?
+    true :
+    this.$__shouldModify(pathToMark, path, options, constructing, parts, schema, val, priorVal);
 
   if (shouldModify) {
-    if (this.$__.primitiveAtomics && this.$__.primitiveAtomics[path]) {
+    if (this.$__.primitiveAtomics?.[path]) {
       delete this.$__.primitiveAtomics[path];
-      if (Object.keys(this.$__.primitiveAtomics).length === 0) {
+      if (utils.hasOwnKeys(this.$__.primitiveAtomics) === false) {
         delete this.$__.primitiveAtomics;
       }
     }
     this.markModified(pathToMark);
 
     // handle directly setting arrays (gh-1126)
-    MongooseArray || (MongooseArray = require('./types/array'));
     if (val && utils.isMongooseArray(val)) {
       val._registerAtomic('$set', val);
 
@@ -1788,8 +1820,8 @@ Document.prototype.$__set = function(pathToMark, path, options, constructing, pa
 /**
  * Gets a raw value from a path (no getters)
  *
- * @param {String} path
- * @return {Any} Returns the value from the given `path`.
+ * @param {string} path
+ * @return {any} Returns the value from the given `path`.
  * @api private
  */
 
@@ -1821,8 +1853,8 @@ Document.prototype.$__getValue = function(path) {
  *     doc.counter += 2;
  *     await doc.save(); // Sends a `{ $set: { counter: 2 } }` to MongoDB
  *
- * @param {String|Array} path path or paths to update
- * @param {Number} val increment `path` by this value
+ * @param {string|Array} path path or paths to update
+ * @param {number} val increment `path` by this value
  * @return {Document} this
  */
 
@@ -1879,8 +1911,8 @@ Document.prototype.$inc = function $inc(path, val) {
 /**
  * Sets a raw value for a path (no casting, setters, transformations)
  *
- * @param {String} path
- * @param {Object} value
+ * @param {string} path
+ * @param {object} value
  * @return {Document} this
  * @api private
  */
@@ -1901,12 +1933,12 @@ Document.prototype.$__setValue = function(path, val) {
  *     // dynamic casting to a string
  *     doc.get('age', String) // "47"
  *
- * @param {String} path
- * @param {Schema|String|Number|Buffer|*} [type] optionally specify a type for on-the-fly attributes
- * @param {Object} [options]
- * @param {Boolean} [options.virtuals=false] Apply virtuals before getting this path
- * @param {Boolean} [options.getters=true] If false, skip applying getters and just get the raw value
- * @return {Any}
+ * @param {string} path
+ * @param {Schema|string|number|Buffer|any} [type] optionally specify a type for on-the-fly attributes
+ * @param {object} [options]
+ * @param {boolean} [options.virtuals=false] Apply virtuals before getting this path
+ * @param {boolean} [options.getters=true] If false, skip applying getters and just get the raw value
+ * @return {any}
  * @api public
  */
 
@@ -1942,7 +1974,7 @@ Document.prototype.get = function(path, type, options) {
     return obj;
   }
 
-  if (schema != null && schema.instance === 'Mixed') {
+  if (schema?.instance === 'Mixed') {
     const virtual = this.$__schema.virtualpath(path);
     if (virtual != null) {
       schema = virtual;
@@ -1959,7 +1991,7 @@ Document.prototype.get = function(path, type, options) {
   }
 
   for (let i = 0, l = pieces.length; i < l; i++) {
-    if (obj && obj._doc) {
+    if (obj?._doc) {
       obj = obj._doc;
     }
 
@@ -1998,7 +2030,7 @@ Document.prototype.$get = Document.prototype.get;
 /**
  * Returns the schematype for the given `path`.
  *
- * @param {String} path
+ * @param {string} path
  * @return {SchemaPath}
  * @api private
  * @method $__path
@@ -2027,7 +2059,7 @@ Document.prototype.$__path = function(path) {
  *     doc.markModified('mixed.type');
  *     doc.save() // changes to mixed.type are now persisted
  *
- * @param {String} path the path to mark modified
+ * @param {string} path the path to mark modified
  * @param {Document} [scope] the scope to run validators with
  * @api public
  */
@@ -2067,7 +2099,7 @@ Document.prototype.$__saveInitialState = function $__saveInitialState(path) {
  *     doc.unmarkModified('foo');
  *     doc.save(); // changes to foo will not be persisted
  *
- * @param {String} path the path to unmark modified
+ * @param {string} path the path to unmark modified
  * @api public
  */
 
@@ -2090,7 +2122,7 @@ Document.prototype.unmarkModified = function(path) {
  * @memberOf Document
  * @instance
  * @method $ignore
- * @param {String} path the path to ignore
+ * @param {string} path the path to ignore
  * @api public
  */
 
@@ -2117,7 +2149,7 @@ Document.prototype.$ignore = function(path) {
  *     doc.directModifiedPaths(); // ['nested.bar']
  *     doc.modifiedPaths(); // ['nested', 'nested.bar']
  *
- * @return {String[]}
+ * @return {string[]}
  * @api public
  */
 
@@ -2142,12 +2174,12 @@ Document.prototype.directModifiedPaths = function() {
  *     doc.$isEmpty('nested'); // false
  *     doc.nested.$isEmpty(); // false
  *
- * @param {String} [path]
+ * @param {string} [path]
  * @memberOf Document
  * @instance
  * @api public
  * @method $isEmpty
- * @return {Boolean}
+ * @return {boolean}
  */
 
 Document.prototype.$isEmpty = function(path) {
@@ -2197,9 +2229,9 @@ function _isEmpty(v) {
 /**
  * Returns the list of paths that have been modified.
  *
- * @param {Object} [options]
- * @param {Boolean} [options.includeChildren=false] if true, returns children of modified paths as well. For example, if false, the list of modified paths for `doc.colors = { primary: 'blue' };` will **not** contain `colors.primary`. If true, `modifiedPaths()` will return an array that contains `colors.primary`.
- * @return {String[]}
+ * @param {object} [options]
+ * @param {boolean} [options.includeChildren=false] if true, returns children of modified paths as well. For example, if false, the list of modified paths for `doc.colors = { primary: 'blue' };` will **not** contain `colors.primary`. If true, `modifiedPaths()` will return an array that contains `colors.primary`.
+ * @return {string[]}
  * @api public
  */
 
@@ -2278,16 +2310,16 @@ Document.prototype[documentModifiedPaths] = Document.prototype.modifiedPaths;
  *     doc.isModified('documents otherProp') // true
  *     doc.isDirectModified('documents')     // false
  *
- * @param {String} [path] optional
- * @param {Object} [options]
- * @param {Boolean} [options.ignoreAtomics=false] If true, doesn't return true if path is underneath an array that was modified with atomic operations like `push()`
- * @return {Boolean}
+ * @param {string} [path] optional
+ * @param {object} [options]
+ * @param {boolean} [options.ignoreAtomics=false] If true, doesn't return true if path is underneath an array that was modified with atomic operations like `push()`
+ * @return {boolean}
  * @api public
  */
 
 Document.prototype.isModified = function(paths, options, modifiedPaths) {
   if (paths) {
-    const ignoreAtomics = options && options.ignoreAtomics;
+    const ignoreAtomics = options?.ignoreAtomics;
     const directModifiedPathsObj = this.$__.activePaths.states.modify;
     if (directModifiedPathsObj == null) {
       return false;
@@ -2312,7 +2344,7 @@ Document.prototype.isModified = function(paths, options, modifiedPaths) {
     if (ignoreAtomics) {
       directModifiedPaths = directModifiedPaths.filter(path => {
         const value = this.$__getValue(path);
-        if (value != null && value[arrayAtomicsSymbol] != null && value[arrayAtomicsSymbol].$set === undefined) {
+        if (value?.[arrayAtomicsSymbol] != null && value[arrayAtomicsSymbol].$set === undefined) {
           return false;
         }
         return true;
@@ -2352,8 +2384,8 @@ Document.prototype[documentIsModified] = Document.prototype.isModified;
  * @memberOf Document
  * @instance
  * @method $isDefault
- * @param {String} [path]
- * @return {Boolean}
+ * @param {string} [path]
+ * @return {boolean}
  * @api public
  */
 
@@ -2388,8 +2420,8 @@ Document.prototype.$isDefault = function(path) {
  *     product.deleteOne(); // will execute a remove against the db
  *
  *
- * @param {Boolean} [val] optional, overrides whether mongoose thinks the doc is deleted
- * @return {Boolean|Document} whether mongoose thinks this doc is deleted.
+ * @param {boolean} [val] optional, overrides whether mongoose thinks the doc is deleted
+ * @return {boolean|Document} whether mongoose thinks this doc is deleted.
  * @method $isDeleted
  * @memberOf Document
  * @instance
@@ -2414,8 +2446,8 @@ Document.prototype.$isDeleted = function(val) {
  *     doc.isDirectModified('documents.0.title') // true
  *     doc.isDirectModified('documents') // false
  *
- * @param {String|String[]} [path]
- * @return {Boolean}
+ * @param {string|string[]} [path]
+ * @return {boolean}
  * @api public
  */
 
@@ -2434,7 +2466,7 @@ Document.prototype.isDirectModified = function(path) {
     for (let i = 0; i < pieces.length - 1; ++i) {
       const subpath = pieces.slice(0, i + 1).join('.');
       const subdoc = this.$get(subpath);
-      if (subdoc != null && subdoc.$__ != null && subdoc.isDirectModified(pieces.slice(i + 1).join('.'))) {
+      if (subdoc?.$__ != null && subdoc.isDirectModified(pieces.slice(i + 1).join('.'))) {
         return true;
       }
     }
@@ -2453,8 +2485,8 @@ Document.prototype.isDirectModified = function(path) {
 /**
  * Checks if `path` is in the `init` state, that is, it was set by `Document#init()` and not modified since.
  *
- * @param {String} [path]
- * @return {Boolean}
+ * @param {string} [path]
+ * @return {boolean}
  * @api public
  */
 
@@ -2484,8 +2516,8 @@ Document.prototype.isInit = function(path) {
  *     doc.isSelected('name') // true
  *     doc.isSelected('age')  // false
  *
- * @param {String|String[]} path
- * @return {Boolean}
+ * @param {string|string[]} path
+ * @return {boolean}
  * @api public
  */
 
@@ -2566,8 +2598,8 @@ Document.prototype.$__isSelected = Document.prototype.isSelected;
  *        doc.isDirectSelected('nested')  // false
  *     })
  *
- * @param {String} path
- * @return {Boolean}
+ * @param {string} path
+ * @return {boolean}
  * @api public
  */
 
@@ -2628,10 +2660,13 @@ Document.prototype.isDirectSelected = function isDirectSelected(path) {
  *
  *     await doc.validate({ validateModifiedOnly: false, pathsToSkip: ['name', 'email']});
  *
- * @param {Array|String} [pathsToValidate] list of paths to validate. If set, Mongoose will validate only the modified paths that are in the given list.
- * @param {Object} [options] internal options
- * @param {Boolean} [options.validateModifiedOnly=false] if `true` mongoose validates only modified paths.
+ * @param {Array|string} [pathsToValidate] list of paths to validate. If set, Mongoose will validate only the modified paths that are in the given list.
+ * @param {object} [options] internal options
+ * @param {boolean} [options.validateModifiedOnly=false] if `true` mongoose validates only modified paths.
  * @param {Array|string} [options.pathsToSkip] list of paths to skip. If set, Mongoose will validate every modified path that is not in this list.
+ * @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} Returns a Promise.
  * @api public
  */
@@ -2652,7 +2687,7 @@ Document.prototype.validate = async function validate(pathsToValidate, options)
     const isOnePathOnly = options.pathsToSkip.indexOf(' ') === -1;
     options.pathsToSkip = isOnePathOnly ? [options.pathsToSkip] : options.pathsToSkip.split(' ');
   }
-  const _skipParallelValidateCheck = options && options._skipParallelValidateCheck;
+  const _skipParallelValidateCheck = options?._skipParallelValidateCheck;
 
   if (this.$isSubdocument != null) {
     // Skip parallel validate check for subdocuments
@@ -2662,16 +2697,183 @@ Document.prototype.validate = async function validate(pathsToValidate, options)
     this.$__.validating = true;
   }
 
-  return new Promise((resolve, reject) => {
-    this.$__validate(pathsToValidate, options, (error) => {
-      this.$op = null;
-      this.$__.validating = null;
-      if (error != null) {
-        return reject(error);
+  try {
+    try {
+      [options] = await this._execDocumentPreHooks('validate', options, [options]);
+    } catch (error) {
+      await this._execDocumentPostHooks('validate', options, error);
+      return;
+    }
+
+    if (this.$__.saveOptions && this.$__.saveOptions.pathsToSave && !pathsToValidate) {
+      pathsToValidate = [...this.$__.saveOptions.pathsToSave];
+    }
+
+    const hasValidateModifiedOnlyOption = options &&
+        (typeof options === 'object') &&
+        ('validateModifiedOnly' in options);
+
+    const pathsToSkip = options?.pathsToSkip || null;
+
+    let shouldValidateModifiedOnly;
+    if (hasValidateModifiedOnlyOption) {
+      shouldValidateModifiedOnly = !!options.validateModifiedOnly;
+    } else {
+      shouldValidateModifiedOnly = this.$__schema.options.validateModifiedOnly;
+    }
+    this.$__.validateModifiedOnly = shouldValidateModifiedOnly;
+
+    const validateAllPaths = options?.validateAllPaths;
+    if (validateAllPaths) {
+      if (pathsToSkip) {
+        throw new TypeError('Cannot set both `validateAllPaths` and `pathsToSkip`');
       }
-      resolve();
-    });
-  });
+      if (pathsToValidate) {
+        throw new TypeError('Cannot set both `validateAllPaths` and `pathsToValidate`');
+      }
+      if (hasValidateModifiedOnlyOption && shouldValidateModifiedOnly) {
+        throw new TypeError('Cannot set both `validateAllPaths` and `validateModifiedOnly`');
+      }
+    }
+
+    const _this = this;
+
+    // only validate required fields when necessary
+    let paths;
+    let doValidateOptionsByPath;
+    if (validateAllPaths) {
+      paths = new Set(Object.keys(this.$__schema.paths));
+      // gh-661: if a whole array is modified, make sure to run validation on all
+      // the children as well
+      for (const path of paths) {
+        const schemaType = this.$__schema.path(path);
+        if (!schemaType?.$isMongooseArray) {
+          continue;
+        }
+        const val = this.$__getValue(path);
+        if (!val) {
+          continue;
+        }
+        _pushNestedArrayPaths(val, paths, path);
+      }
+      paths = [...paths];
+      doValidateOptionsByPath = {};
+    } else {
+      const pathDetails = _getPathsToValidate(this, pathsToValidate, pathsToSkip, options?._nestedValidate);
+      paths = shouldValidateModifiedOnly ?
+        pathDetails[0].filter((path) => this.$isModified(path)) :
+        pathDetails[0];
+      doValidateOptionsByPath = pathDetails[1];
+    }
+
+    if (typeof pathsToValidate === 'string') {
+      pathsToValidate = pathsToValidate.split(' ');
+    }
+
+    if (paths.length === 0) {
+      const error = _completeValidate(this);
+
+      await this._execDocumentPostHooks('validate', options, error);
+      return;
+    }
+
+    const validated = {};
+
+    const pathsToSave = Array.isArray(this.$__.saveOptions?.pathsToSave) ?
+      new Set(this.$__.saveOptions.pathsToSave) :
+      null;
+    const promises = [];
+    for (let i = 0; i < paths.length; ++i) {
+      const path = paths[i];
+      if (pathsToSave != null && !pathsToSave.has(path)) {
+        promises.push(Promise.resolve(null));
+        continue;
+      }
+      if (path == null || validated[path]) {
+        promises.push(Promise.resolve(null));
+        continue;
+      }
+
+      validated[path] = true;
+      const schemaType = _this.$__schema.path(path);
+
+      if (!schemaType) {
+        promises.push(Promise.resolve(null));
+        continue;
+      }
+
+      // If user marked as invalid or there was a cast error, don't validate
+      if (!_this.$isValid(path)) {
+        promises.push(Promise.resolve(null));
+        continue;
+      }
+
+      // If setting a path under a mixed path, avoid using the mixed path validator (gh-10141)
+      if (schemaType[schemaMixedSymbol] != null && path !== schemaType.path) {
+        promises.push(Promise.resolve(null));
+        continue;
+      }
+
+      let val = _this.$__getValue(path);
+
+      // If you `populate()` and get back a null value, required validators
+      // shouldn't fail (gh-8018). We should always fall back to the populated
+      // value.
+      let pop;
+      if ((pop = _this.$populated(path))) {
+        val = pop;
+      } else if (val?.$__?.wasPopulated) {
+        // Array paths, like `somearray.1`, do not show up as populated with `$populated()`,
+        // so in that case pull out the document's id
+        val = val._doc._id;
+      }
+      const scope = _this.$__.pathsToScopes != null && path in _this.$__.pathsToScopes ?
+        _this.$__.pathsToScopes[path] :
+        _this;
+
+      const doValidateOptions = {
+        ...doValidateOptionsByPath[path],
+        path: path,
+        validateAllPaths,
+        _nestedValidate: true
+      };
+
+      promises.push(
+        schemaType.doValidate(val, scope, doValidateOptions).then(
+          () => null,
+          err => {
+            const isSubdoc = schemaType.$isSingleNested ||
+                schemaType.$isArraySubdocument ||
+                schemaType.$isMongooseDocumentArray;
+            if (isSubdoc && err instanceof ValidationError) {
+              return null;
+            }
+
+            return err;
+          }
+        )
+      );
+    }
+    const validationErrors = await Promise.all(promises);
+    for (let i = 0; i < validationErrors.length; ++i) {
+      const validationError = validationErrors[i];
+      if (validationError == null) {
+        continue;
+      }
+      if (this.$__.validationError == null) {
+        this.$__.validationError = new ValidationError(this);
+      }
+      _this.invalidate(paths[i], validationError, undefined, true);
+    }
+
+    const error = _completeValidate(this);
+
+    await this._execDocumentPostHooks('validate', options, error);
+  } finally {
+    delete this.$__.validateModifiedOnly;
+    this.$op = null;
+    this.$__.validating = null;
+  }
 };
 
 /**
@@ -2685,9 +2887,49 @@ Document.prototype.validate = async function validate(pathsToValidate, options)
 Document.prototype.$validate = Document.prototype.validate;
 
 /*!
- * ignore
+ * Event emitting and error persisting logic that needs to happen in both the `paths.length === 0`
+ * and `paths.length > 0` cases in `Document.prototype.validate()`.
+ *
+ * @param {Document} doc
+ * @return {Error}
+ * @private
  */
 
+function _completeValidate(doc) {
+  let error = doc.$__.validationError;
+  doc.$__.validationError = null;
+  doc.$__.validating = null;
+
+  if (doc.$__.validateModifiedOnly && error != null) {
+    // Remove any validation errors that aren't from modified paths
+    const errors = Object.keys(error.errors);
+    for (const errPath of errors) {
+      if (!doc.$isModified(errPath)) {
+        delete error.errors[errPath];
+      }
+    }
+    if (utils.hasOwnKeys(error.errors) === false) {
+      error = void 0;
+    }
+  }
+
+  doc.$__.cachedRequired = {};
+  doc.$emit('validate', doc);
+  doc.constructor.emit('validate', doc);
+
+  if (error) {
+    for (const key in error.errors) {
+      // Make sure cast errors persist
+      if (!doc[documentArrayParent] &&
+          error.errors[key] instanceof MongooseError.CastError) {
+        doc.invalidate(key, error.errors[key]);
+      }
+    }
+  }
+
+  return error;
+}
+
 function _evaluateRequiredFunctions(doc) {
   const requiredFields = Object.keys(doc.$__.activePaths.getStatePaths('require'));
   let i = 0;
@@ -2697,7 +2939,7 @@ function _evaluateRequiredFunctions(doc) {
 
     const p = doc.$__schema.path(path);
 
-    if (p != null && typeof p.originalRequiredValue === 'function') {
+    if (typeof p?.originalRequiredValue === 'function') {
       doc.$__.cachedRequired = doc.$__.cachedRequired || {};
       try {
         doc.$__.cachedRequired[path] = p.originalRequiredValue.call(doc, doc);
@@ -2739,9 +2981,40 @@ function _getPathsToValidate(doc, pathsToValidate, pathsToSkip, isNestedValidate
       // Skip $* paths - they represent map schemas, not actual document paths
       return;
     }
+
+    const _pathType = doc.$__schema.path(p);
+
+    // Optimization: if primitive path with no validators, or array of primitives
+    // with no validators, skip validating this path entirely.
+    // Note: paths with no _pathType (e.g. sub-paths under Mixed) must still be
+    // added, as they trigger validation of the parent Mixed path.
+    if (_pathType) {
+      if (!_pathType.schema &&
+        !_pathType.embeddedSchemaType &&
+        _pathType.validators.length === 0 &&
+        !_pathType.$parentSchemaDocArray &&
+        // gh-15957: skip this optimization for SchemaMap as maps can contain subdocuments
+        // that need validation even if the map itself has no validators
+        !_pathType.$isSchemaMap &&
+        !_pathType.$isSchemaUnion) {
+        return;
+      } else if (_pathType.$isMongooseArray &&
+        !_pathType.$isMongooseDocumentArray && // Skip document arrays...
+        !_pathType.embeddedSchemaType.$isMongooseArray && // and arrays of arrays
+        _pathType.validators.length === 0 && // and arrays with top-level validators
+        _pathType.embeddedSchemaType.validators.length === 0) {
+        return;
+      }
+    }
+
     paths.add(p);
   }
 
+  const onlyPrimitiveValues = doc.$__hasOnlyPrimitiveValues();
+  if (onlyPrimitiveValues && paths.size === 0) {
+    return [[], doValidateOptions];
+  }
+
   if (!isNestedValidate) {
     // If we're validating a subdocument, all this logic will run anyway on the top-level document, so skip for subdocuments.
     // But only run for top-level subdocuments, because we're looking for subdocuments that are not modified at top-level but
@@ -2757,7 +3030,7 @@ function _getPathsToValidate(doc, pathsToValidate, pathsToSkip, isNestedValidate
         }
       } else if (schemaType.$isMongooseDocumentArray) {
         const arr = doc.$get(path);
-        if (arr && arr.length) {
+        if (arr?.length) {
           for (const subdoc of arr) {
             if (subdoc) {
               topLevelSubdocs.push(subdoc);
@@ -2806,31 +3079,17 @@ function _getPathsToValidate(doc, pathsToValidate, pathsToSkip, isNestedValidate
     }
   }
 
-  for (const path of paths) {
-    const _pathType = doc.$__schema.path(path);
-    if (!_pathType) {
-      continue;
-    }
-
-    if (_pathType.$isMongooseDocumentArray) {
-      for (const p of paths) {
-        if (p == null || p.startsWith(_pathType.path + '.')) {
-          paths.delete(p);
+  if (!onlyPrimitiveValues) {
+    for (const path of paths) {
+      const _pathType = doc.$__schema.path(path);
+      if (_pathType && _pathType.$isMongooseDocumentArray) {
+        for (const p of paths) {
+          if (p == null || p.startsWith(_pathType.path + '.')) {
+            paths.delete(p);
+          }
         }
       }
     }
-
-    // Optimization: if primitive path with no validators, or array of primitives
-    // with no validators, skip validating this path entirely.
-    if (!_pathType.caster && _pathType.validators.length === 0 && !_pathType.$parentSchemaDocArray) {
-      paths.delete(path);
-    } else if (_pathType.$isMongooseArray &&
-      !_pathType.$isMongooseDocumentArray && // Skip document arrays...
-      !_pathType.$embeddedSchemaType.$isMongooseArray && // and arrays of arrays
-      _pathType.validators.length === 0 && // and arrays with top-level validators
-      _pathType.$embeddedSchemaType.validators.length === 0) {
-      paths.delete(path);
-    }
   }
 
 
@@ -2910,7 +3169,7 @@ function _addArrayPathsToValidate(doc, paths) {
         // it unless we have a case of #6364
         (!Array.isArray(_pathType) &&
           _pathType.$isMongooseDocumentArray &&
-          !(_pathType && _pathType.schemaOptions && _pathType.schemaOptions.required))) {
+          !_pathType?.schemaOptions?.required)) {
       continue;
     }
 
@@ -2918,8 +3177,8 @@ function _addArrayPathsToValidate(doc, paths) {
     // on the array type, there's no need to run validation on the individual array elements.
     if (_pathType.$isMongooseArray &&
         !_pathType.$isMongooseDocumentArray && // Skip document arrays...
-        !_pathType.$embeddedSchemaType.$isMongooseArray && // and arrays of arrays
-        _pathType.$embeddedSchemaType.validators.length === 0) {
+        !_pathType.embeddedSchemaType.$isMongooseArray && // and arrays of arrays
+        _pathType.embeddedSchemaType.validators.length === 0) {
       continue;
     }
 
@@ -2945,217 +3204,18 @@ function _pushNestedArrayPaths(val, paths, path) {
  * ignore
  */
 
-Document.prototype.$__validate = function(pathsToValidate, options, callback) {
-  if (this.$__.saveOptions && this.$__.saveOptions.pathsToSave && !pathsToValidate) {
-    pathsToValidate = [...this.$__.saveOptions.pathsToSave];
-  } else if (typeof pathsToValidate === 'function') {
-    callback = pathsToValidate;
-    options = null;
-    pathsToValidate = null;
-  } else if (typeof options === 'function') {
-    callback = options;
-    options = null;
-  }
-
-  const hasValidateModifiedOnlyOption = options &&
-      (typeof options === 'object') &&
-      ('validateModifiedOnly' in options);
-
-  const pathsToSkip = (options && options.pathsToSkip) || null;
-
-  let shouldValidateModifiedOnly;
-  if (hasValidateModifiedOnlyOption) {
-    shouldValidateModifiedOnly = !!options.validateModifiedOnly;
-  } else {
-    shouldValidateModifiedOnly = this.$__schema.options.validateModifiedOnly;
-  }
-
-  const validateAllPaths = options && options.validateAllPaths;
-  if (validateAllPaths) {
-    if (pathsToSkip) {
-      throw new TypeError('Cannot set both `validateAllPaths` and `pathsToSkip`');
-    }
-    if (pathsToValidate) {
-      throw new TypeError('Cannot set both `validateAllPaths` and `pathsToValidate`');
-    }
-    if (hasValidateModifiedOnlyOption && shouldValidateModifiedOnly) {
-      throw new TypeError('Cannot set both `validateAllPaths` and `validateModifiedOnly`');
-    }
-  }
-
-  const _this = this;
-  const _complete = () => {
-    let validationError = this.$__.validationError;
-    this.$__.validationError = null;
-    this.$__.validating = null;
-
-    if (shouldValidateModifiedOnly && validationError != null) {
-      // Remove any validation errors that aren't from modified paths
-      const errors = Object.keys(validationError.errors);
-      for (const errPath of errors) {
-        if (!this.$isModified(errPath)) {
-          delete validationError.errors[errPath];
-        }
-      }
-      if (Object.keys(validationError.errors).length === 0) {
-        validationError = void 0;
-      }
-    }
-
-    this.$__.cachedRequired = {};
-    this.$emit('validate', _this);
-    this.constructor.emit('validate', _this);
-
-    if (validationError) {
-      for (const key in validationError.errors) {
-        // Make sure cast errors persist
-        if (!this[documentArrayParent] &&
-            validationError.errors[key] instanceof MongooseError.CastError) {
-          this.invalidate(key, validationError.errors[key]);
-        }
-      }
-
-      return validationError;
-    }
-  };
-
-  // only validate required fields when necessary
-  let paths;
-  let doValidateOptionsByPath;
-  if (validateAllPaths) {
-    paths = new Set(Object.keys(this.$__schema.paths));
-    // gh-661: if a whole array is modified, make sure to run validation on all
-    // the children as well
-    for (const path of paths) {
-      const schemaType = this.$__schema.path(path);
-      if (!schemaType || !schemaType.$isMongooseArray) {
-        continue;
-      }
-      const val = this.$__getValue(path);
-      if (!val) {
-        continue;
-      }
-      _pushNestedArrayPaths(val, paths, path);
-    }
-    paths = [...paths];
-    doValidateOptionsByPath = {};
-  } else {
-    const pathDetails = _getPathsToValidate(this, pathsToValidate, pathsToSkip, options && options._nestedValidate);
-    paths = shouldValidateModifiedOnly ?
-      pathDetails[0].filter((path) => this.$isModified(path)) :
-      pathDetails[0];
-    doValidateOptionsByPath = pathDetails[1];
-  }
-
-  if (typeof pathsToValidate === 'string') {
-    pathsToValidate = pathsToValidate.split(' ');
-  }
-
-  if (paths.length === 0) {
-    return immediate(function() {
-      const error = _complete();
-      if (error) {
-        return _this.$__schema.s.hooks.execPost('validate:error', _this, [_this], { error: error }, function(error) {
-          callback(error);
-        });
-      }
-      callback(null, _this);
-    });
-  }
-
-  const validated = {};
-  let total = 0;
-
-  let pathsToSave = this.$__.saveOptions?.pathsToSave;
-  if (Array.isArray(pathsToSave)) {
-    pathsToSave = new Set(pathsToSave);
-    for (const path of paths) {
-      if (!pathsToSave.has(path)) {
-        continue;
-      }
-      validatePath(path);
-    }
-  } else {
-    for (const path of paths) {
-      validatePath(path);
-    }
-  }
-
-  function validatePath(path) {
-    if (path == null || validated[path]) {
-      return;
-    }
-
-    validated[path] = true;
-    total++;
-
-    immediate(function() {
-      const schemaType = _this.$__schema.path(path);
-
-      if (!schemaType) {
-        return --total || complete();
-      }
-
-      // If user marked as invalid or there was a cast error, don't validate
-      if (!_this.$isValid(path)) {
-        --total || complete();
-        return;
-      }
-
-      // If setting a path under a mixed path, avoid using the mixed path validator (gh-10141)
-      if (schemaType[schemaMixedSymbol] != null && path !== schemaType.path) {
-        return --total || complete();
-      }
-
-      let val = _this.$__getValue(path);
-
-      // If you `populate()` and get back a null value, required validators
-      // shouldn't fail (gh-8018). We should always fall back to the populated
-      // value.
-      let pop;
-      if ((pop = _this.$populated(path))) {
-        val = pop;
-      } else if (val != null && val.$__ != null && val.$__.wasPopulated) {
-        // Array paths, like `somearray.1`, do not show up as populated with `$populated()`,
-        // so in that case pull out the document's id
-        val = val._doc._id;
-      }
-      const scope = _this.$__.pathsToScopes != null && path in _this.$__.pathsToScopes ?
-        _this.$__.pathsToScopes[path] :
-        _this;
-
-      const doValidateOptions = {
-        ...doValidateOptionsByPath[path],
-        path: path,
-        validateAllPaths,
-        _nestedValidate: true
-      };
-
-      schemaType.doValidate(val, function(err) {
-        if (err) {
-          const isSubdoc = schemaType.$isSingleNested ||
-              schemaType.$isArraySubdocument ||
-              schemaType.$isMongooseDocumentArray;
-          if (isSubdoc && err instanceof ValidationError) {
-            return --total || complete();
-          }
-          _this.invalidate(path, err, undefined, true);
-        }
-        --total || complete();
-      }, scope, doValidateOptions);
-    });
-  }
+Document.prototype._execDocumentPreHooks = async function _execDocumentPreHooks(opName, options, argsForHooks) {
+  const filter = buildMiddlewareFilter(options, 'pre');
+  return this.$__middleware.execPre(opName, this, argsForHooks || [], { filter });
+};
 
-  function complete() {
-    const error = _complete();
-    if (error) {
-      return _this.$__schema.s.hooks.execPost('validate:error', _this, [_this], { error: error }, function(error) {
-        callback(error);
-      });
-    }
-    callback(null, _this);
-  }
+/*!
+ * ignore
+ */
 
+Document.prototype._execDocumentPostHooks = async function _execDocumentPostHooks(opName, options, error) {
+  const filter = buildMiddlewareFilter(options, 'post');
+  return this.$__middleware.execPost(opName, this, [this], { error, filter });
 };
 
 /*!
@@ -3218,9 +3278,12 @@ function _handlePathsToSkip(paths, pathsToSkip) {
  *     }
  *
  * @param {Array|string} [pathsToValidate] only validate the given paths
- * @param {Object} [options] options for validation
- * @param {Boolean} [options.validateModifiedOnly=false] If `true`, Mongoose will only validate modified paths, as opposed to modified paths and `required` paths.
+ * @param {object} [options] options for validation
+ * @param {boolean} [options.validateModifiedOnly=false] If `true`, Mongoose will only validate modified paths, as opposed to modified paths and `required` paths.
  * @param {Array|string} [options.pathsToSkip] list of paths to skip. If set, Mongoose will validate every modified path that is not in this list.
+ * @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 {ValidationError|undefined} ValidationError if there are errors during validation, or undefined if there is no error.
  * @api public
  */
@@ -3244,9 +3307,9 @@ Document.prototype.validateSync = function(pathsToValidate, options) {
     shouldValidateModifiedOnly = this.$__schema.options.validateModifiedOnly;
   }
 
-  let pathsToSkip = options && options.pathsToSkip;
+  let pathsToSkip = options?.pathsToSkip;
 
-  const validateAllPaths = options && options.validateAllPaths;
+  const validateAllPaths = options?.validateAllPaths;
   if (validateAllPaths) {
     if (pathsToSkip) {
       throw new TypeError('Cannot set both `validateAllPaths` and `pathsToSkip`');
@@ -3272,7 +3335,7 @@ Document.prototype.validateSync = function(pathsToValidate, options) {
     // the children as well
     for (const path of paths) {
       const schemaType = this.$__schema.path(path);
-      if (!schemaType || !schemaType.$isMongooseArray) {
+      if (!schemaType?.$isMongooseArray) {
         continue;
       }
       const val = this.$__getValue(path);
@@ -3368,10 +3431,10 @@ Document.prototype.validateSync = function(pathsToValidate, options) {
  *               value: 14 } } }
  *     })
  *
- * @param {String} path the field to invalidate. For array elements, use the `array.i.field` syntax, where `i` is the 0-based index in the array.
- * @param {String|Error} err the error which states the reason `path` was invalid
- * @param {Object|String|Number|any} val optional invalid value
- * @param {String} [kind] optional `kind` property for the error
+ * @param {string} path the field to invalidate. For array elements, use the `array.i.field` syntax, where `i` is the 0-based index in the array.
+ * @param {string|Error} err the error which states the reason `path` was invalid
+ * @param {object|string|number|any} val optional invalid value
+ * @param {string} [kind] optional `kind` property for the error
  * @return {ValidationError} the current ValidationError, with all currently invalidated paths
  * @api public
  */
@@ -3405,7 +3468,7 @@ Document.prototype.invalidate = function(path, err, val, kind) {
 /**
  * Marks a path as valid, removing existing validation errors.
  *
- * @param {String} path the field to mark as valid
+ * @param {string} path the field to mark as valid
  * @api public
  * @memberOf Document
  * @instance
@@ -3413,12 +3476,12 @@ Document.prototype.invalidate = function(path, err, val, kind) {
  */
 
 Document.prototype.$markValid = function(path) {
-  if (!this.$__.validationError || !this.$__.validationError.errors[path]) {
+  if (!this.$__.validationError?.errors[path]) {
     return;
   }
 
   delete this.$__.validationError.errors[path];
-  if (Object.keys(this.$__.validationError.errors).length === 0) {
+  if (utils.hasOwnKeys(this.$__.validationError.errors) === false) {
     this.$__.validationError = null;
   }
 };
@@ -3438,7 +3501,7 @@ function _markValidSubpaths(doc, path) {
       delete doc.$__.validationError.errors[key];
     }
   }
-  if (Object.keys(doc.$__.validationError.errors).length === 0) {
+  if (utils.hasOwnKeys(doc.$__.validationError.errors) === false) {
     doc.$__.validationError = null;
   }
 }
@@ -3483,16 +3546,16 @@ function _checkImmutableSubpaths(subdoc, schematype, priorVal) {
  *     const newProduct = await product.save();
  *     newProduct === product; // true
  *
- * @param {Object} [options] options optional options
+ * @param {object} [options] options optional options
  * @param {Session} [options.session=null] the [session](https://www.mongodb.com/docs/manual/reference/server-sessions/) associated with this save operation. If not specified, defaults to the [document's associated session](https://mongoosejs.com/docs/api/document.html#Document.prototype.$session()).
- * @param {Object} [options.safe] (DEPRECATED) overrides [schema's safe option](https://mongoosejs.com/docs/guide.html#safe). Use the `w` option instead.
- * @param {Boolean} [options.validateBeforeSave] set to false to save without validating.
- * @param {Boolean} [options.validateModifiedOnly=false] If `true`, Mongoose will only validate modified paths, as opposed to modified paths and `required` paths.
- * @param {Number|String} [options.w] set the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern/#w-option). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern)
- * @param {Boolean} [options.j] set to true for MongoDB to wait until this `save()` has been [journaled before resolving the returned promise](https://www.mongodb.com/docs/manual/reference/write-concern/#j-option). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern)
- * @param {Number} [options.wtimeout] sets a [timeout for the write concern](https://www.mongodb.com/docs/manual/reference/write-concern/#wtimeout). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern).
- * @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://www.mongodb.com/docs/manual/reference/limits/#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 {object} [options.safe] (DEPRECATED) overrides [schema's safe option](https://mongoosejs.com/docs/guide.html#safe). Use the `w` option instead.
+ * @param {boolean} [options.validateBeforeSave] set to false to save without validating.
+ * @param {boolean} [options.validateModifiedOnly=false] If `true`, Mongoose will only validate modified paths, as opposed to modified paths and `required` paths.
+ * @param {number|string} [options.w] set the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern/#w-option). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern)
+ * @param {boolean} [options.j] set to true for MongoDB to wait until this `save()` has been [journaled before resolving the returned promise](https://www.mongodb.com/docs/manual/reference/write-concern/#j-option). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern)
+ * @param {number} [options.wtimeout] sets a [timeout for the write concern](https://www.mongodb.com/docs/manual/reference/write-concern/#wtimeout). Overrides the [schema-level `writeConcern` option](https://mongoosejs.com/docs/guide.html#writeConcern).
+ * @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://www.mongodb.com/docs/manual/reference/limits/#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()`.
  * @method save
  * @memberOf Document
  * @instance
@@ -3505,7 +3568,7 @@ function _checkImmutableSubpaths(subdoc, schematype, priorVal) {
 /**
  * Checks if a path is invalid
  *
- * @param {String|String[]} [path] the field to check. If unset will always return "false"
+ * @param {string|string[]} [path] the field to check. If unset will always return "false"
  * @method $isValid
  * @memberOf Document
  * @instance
@@ -3513,7 +3576,7 @@ function _checkImmutableSubpaths(subdoc, schematype, priorVal) {
  */
 
 Document.prototype.$isValid = function(path) {
-  if (this.$__.validationError == null || Object.keys(this.$__.validationError.errors).length === 0) {
+  if (this.$__.validationError == null || utils.hasOwnKeys(this.$__.validationError.errors) === false) {
     return true;
   }
   if (path == null) {
@@ -3543,25 +3606,21 @@ Document.prototype.$isValid = function(path) {
 Document.prototype.$__reset = function reset() {
   let _this = this;
 
-  // Skip for subdocuments
-  const subdocs = !this.$isSubdocument ? this.$getAllSubdocs({ useCache: true }) : null;
-  if (subdocs && subdocs.length > 0) {
+  const onlyPrimitiveValues = this.$__hasOnlyPrimitiveValues();
+
+  // Skip for subdocuments. Also skip if doc only has primitive values,
+  // because primitives can't be subdocs.
+  const subdocs = !this.$isSubdocument && !onlyPrimitiveValues ? this.$getAllSubdocs({ useCache: true }) : null;
+  if (subdocs?.length > 0) {
     for (const subdoc of subdocs) {
       subdoc.$__reset();
     }
   }
 
-  // clear atomics
-  this.$__dirty().forEach(function(dirt) {
-    const type = dirt.value;
-
-    if (type && typeof type.clearAtomics === 'function') {
-      type.clearAtomics();
-    } else if (type && type[arrayAtomicsSymbol]) {
-      type[arrayAtomicsBackupSymbol] = type[arrayAtomicsSymbol];
-      type[arrayAtomicsSymbol] = {};
-    }
-  });
+  // Clear atomics on dirty paths. Walk the modified and default paths
+  // directly instead of calling $__dirty(), which builds intermediate
+  // arrays, a Map, and does parent-path deduplication we don't need here.
+  this.$__resetAtomics();
 
   this.$__.backup = {};
   this.$__.backup.activePaths = {
@@ -3584,12 +3643,46 @@ Document.prototype.$__reset = function reset() {
   return this;
 };
 
+/*!
+ * Clear atomics on all dirty (modified + default) paths. This is a lighter
+ * alternative to calling `$__dirty()` when we only need to clear atomics
+ * and don't need the full {path, value, schema} objects or parent-path
+ * deduplication.
+ */
+
+Document.prototype.$__resetAtomics = function $__resetAtomics() {
+  const activePaths = this.$__.activePaths;
+  const modifyPaths = activePaths.getStatePaths('modify');
+  const defaultPaths = activePaths.getStatePaths('default');
+
+  _clearAtomicsOnPaths(this, modifyPaths);
+  _clearAtomicsOnPaths(this, defaultPaths);
+};
+
+function _clearAtomicsOnPaths(doc, paths) {
+  if (paths == null) {
+    return;
+  }
+  const keys = Object.keys(paths);
+  for (let i = 0; i < keys.length; ++i) {
+    const type = doc.$__getValue(keys[i]);
+    if (type != null) {
+      if (typeof type.clearAtomics === 'function') {
+        type.clearAtomics();
+      } else if (type[arrayAtomicsSymbol]) {
+        type[arrayAtomicsBackupSymbol] = type[arrayAtomicsSymbol];
+        type[arrayAtomicsSymbol] = {};
+      }
+    }
+  }
+}
+
 /*!
  * ignore
  */
 
 Document.prototype.$__undoReset = function $__undoReset() {
-  if (this.$__.backup == null || this.$__.backup.activePaths == null) {
+  if (this.$__.backup?.activePaths == null) {
     return;
   }
 
@@ -3602,7 +3695,7 @@ Document.prototype.$__undoReset = function $__undoReset() {
   for (const dirt of this.$__dirty()) {
     const type = dirt.value;
 
-    if (type && type[arrayAtomicsSymbol] && type[arrayAtomicsBackupSymbol]) {
+    if (type?.[arrayAtomicsSymbol] && type[arrayAtomicsBackupSymbol]) {
       type[arrayAtomicsSymbol] = type[arrayAtomicsBackupSymbol];
     }
   }
@@ -3657,15 +3750,17 @@ Document.prototype.$__dirty = function() {
     }
 
     let top = null;
+    let foundParent = false;
 
     const array = parentPaths(item.path);
     for (let i = 0; i < array.length - 1; i++) {
       if (allPaths.has(array[i])) {
         top = allPaths.get(array[i]);
+        foundParent = true;
         break;
       }
     }
-    if (top == null) {
+    if (!foundParent) {
       minimal.push(item);
     } else if (top != null &&
         top[arrayAtomicsSymbol] != null &&
@@ -3702,6 +3797,7 @@ Document.prototype.$__setSchema = function(schema) {
     this.schema = schema;
   }
   this.$__schema = schema;
+  this.$__middleware = schema._getDocumentMiddleware();
   this[documentSchemaSymbol] = schema;
 };
 
@@ -3738,7 +3834,7 @@ Document.prototype.$__getArrayPathsToValidate = function() {
 /**
  * Get all subdocs (by bfs)
  *
- * @param {Object} [options] options. Currently for internal use.
+ * @param {object} [options] options. Currently for internal use.
  * @return {Array}
  * @api public
  * @method $getAllSubdocs
@@ -3769,14 +3865,14 @@ Document.prototype.$getAllSubdocs = function(options) {
       }
       if (Array.isArray(val)) {
         for (const el of val) {
-          if (el != null && el.$__) {
+          if (el?.$__) {
             newSubdocs.push(el);
           }
         }
       }
       if (val instanceof Map) {
         for (const el of val.values()) {
-          if (el != null && el.$__) {
+          if (el?.$__) {
             newSubdocs.push(el);
           }
         }
@@ -3823,7 +3919,7 @@ Document.prototype.$__handleReject = function handleReject(err) {
   // emit on the Model if listening
   if (this.$listeners('error').length) {
     this.$emit('error', err);
-  } else if (this.constructor.listeners && this.constructor.listeners('error').length) {
+  } else if (this.constructor.listeners?.('error').length) {
     this.constructor.emit('error', err);
   }
 };
@@ -3831,7 +3927,7 @@ Document.prototype.$__handleReject = function handleReject(err) {
 /**
  * Internal common logic for toObject() and toJSON()
  *
- * @return {Object}
+ * @return {object}
  * @api private
  * @method $toObject
  * @memberOf Document
@@ -3852,7 +3948,7 @@ Document.prototype.$toObject = function(options, json) {
     _minimize = options.minimize;
   } else if (this.$__schemaTypeOptions?.minimize != null) {
     _minimize = this.$__schemaTypeOptions.minimize;
-  } else if (defaultOptions != null && defaultOptions.minimize != null) {
+  } else if (defaultOptions?.minimize != null) {
     _minimize = defaultOptions.minimize;
   } else {
     _minimize = this.$__schema.options.minimize;
@@ -4011,7 +4107,7 @@ Document.prototype.$__toObjectShallow = function $__toObjectShallow(schemaFields
 /**
  * Converts this document into a plain-old JavaScript object ([POJO](https://masteringjs.io/tutorials/fundamentals/pojo)).
  *
- * Buffers are converted to instances of [mongodb.Binary](https://mongodb.github.io/node-mongodb-native/4.9/classes/Binary.html) for proper storage.
+ * Buffers are converted to instances of [mongodb.Binary](https://mongodb.github.io/node-mongodb-native/7.0/classes/BSON.Binary.html) for proper storage.
  *
  * #### Getters/Virtuals
  *
@@ -4139,21 +4235,21 @@ Document.prototype.$__toObjectShallow = function $__toObjectShallow(schemaFields
  *
  * _During save, no custom options are applied to the document before being sent to the database._
  *
- * @param {Object} [options]
- * @param {Boolean} [options.getters=false] if true, apply all getters, including virtuals
- * @param {Boolean|Object} [options.virtuals=false] if true, apply virtuals, including aliases. Use `{ getters: true, virtuals: false }` to just apply getters, not virtuals. An object of the form `{ pathsToSkip: ['someVirtual'] }` may also be used to omit specific virtuals.
- * @param {Boolean} [options.aliases=true] if `options.virtuals = true`, you can set `options.aliases = false` to skip applying aliases. This option is a no-op if `options.virtuals = false`.
- * @param {Boolean} [options.minimize=true] if true, omit any empty objects from the output
+ * @param {object} [options]
+ * @param {boolean} [options.getters=false] if true, apply all getters, including virtuals
+ * @param {boolean|object} [options.virtuals=false] if true, apply virtuals, including aliases. Use `{ getters: true, virtuals: false }` to just apply getters, not virtuals. An object of the form `{ pathsToSkip: ['someVirtual'] }` may also be used to omit specific virtuals.
+ * @param {boolean} [options.aliases=true] if `options.virtuals = true`, you can set `options.aliases = false` to skip applying aliases. This option is a no-op if `options.virtuals = false`.
+ * @param {boolean} [options.minimize=true] if true, omit any empty objects from the output
  * @param {Function|null} [options.transform=null] if set, mongoose will call this function to allow you to transform the returned object
- * @param {Boolean} [options.depopulate=false] if true, replace any conventionally populated paths with the original id in the output. Has no affect on virtual populated paths.
- * @param {Boolean} [options.versionKey=true] if false, exclude the version key (`__v` by default) from the output
- * @param {Boolean} [options.flattenMaps=false] if true, convert Maps to POJOs. Useful if you want to `JSON.stringify()` the result of `toObject()`.
- * @param {Boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
- * @param {Boolean} [options.flattenUUIDs=false] if true, convert any UUIDs in the result to 36-character UUID strings in 8-4-4-4-12 format.
- * @param {Boolean} [options.useProjection=false] - If true, omits fields that are excluded in this document's projection. Unless you specified a projection, this will omit any field that has `select: false` in the schema.
- * @param {Boolean} [options.schemaFieldsOnly=false] - If true, the resulting object will only have fields that are defined in the document's schema. By default, `toObject()` returns all fields in the underlying document from MongoDB, including ones that are not listed in the schema.
- * @return {Object} document as a plain old JavaScript object (POJO). This object may contain ObjectIds, Maps, Dates, mongodb.Binary, Buffers, and other non-POJO values.
- * @see mongodb.Binary https://mongodb.github.io/node-mongodb-native/4.9/classes/Binary.html
+ * @param {boolean} [options.depopulate=false] if true, replace any conventionally populated paths with the original id in the output. Has no affect on virtual populated paths.
+ * @param {boolean} [options.versionKey=true] if false, exclude the version key (`__v` by default) from the output
+ * @param {boolean} [options.flattenMaps=false] if true, convert Maps to POJOs. Useful if you want to `JSON.stringify()` the result of `toObject()`.
+ * @param {boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
+ * @param {boolean} [options.flattenUUIDs=false] if true, convert any UUIDs in the result to 36-character UUID strings in 8-4-4-4-12 format.
+ * @param {boolean} [options.useProjection=false] - If true, omits fields that are excluded in this document's projection. Unless you specified a projection, this will omit any field that has `select: false` in the schema.
+ * @param {boolean} [options.schemaFieldsOnly=false] - If true, the resulting object will only have fields that are defined in the document's schema. By default, `toObject()` returns all fields in the underlying document from MongoDB, including ones that are not listed in the schema.
+ * @return {object} document as a plain old JavaScript object (POJO). This object may contain ObjectIds, Maps, Dates, mongodb.Binary, Buffers, and other non-POJO values.
+ * @see mongodb.Binary https://mongodb.github.io/node-mongodb-native/7.0/classes/BSON.Binary.html
  * @api public
  * @memberOf Document
  * @instance
@@ -4177,7 +4273,7 @@ function applyVirtuals(self, json, options, toObjectOptions) {
   let assignPath;
   let cur = self._doc;
   let v;
-  const aliases = typeof (toObjectOptions && toObjectOptions.aliases) === 'boolean'
+  const aliases = typeof toObjectOptions?.aliases === 'boolean'
     ? toObjectOptions.aliases
     : true;
 
@@ -4185,7 +4281,7 @@ function applyVirtuals(self, json, options, toObjectOptions) {
   let virtualsToApply = null;
   if (Array.isArray(options.virtuals)) {
     virtualsToApply = new Set(options.virtuals);
-  } else if (options.virtuals && options.virtuals.pathsToSkip) {
+  } else if (options.virtuals?.pathsToSkip) {
     virtualsToApply = new Set(paths);
     for (let i = 0; i < options.virtuals.pathsToSkip.length; i++) {
       if (virtualsToApply.has(options.virtuals.pathsToSkip[i])) {
@@ -4251,8 +4347,8 @@ function applyVirtuals(self, json, options, toObjectOptions) {
  * Applies virtuals properties to `json`.
  *
  * @param {Document} self
- * @param {Object} json
- * @return {Object} `json`
+ * @param {object} json
+ * @return {object} `json`
  * @api private
  */
 
@@ -4296,9 +4392,9 @@ function applyGetters(self, json) {
           branch[part],
           self
         );
-        if (Array.isArray(branch[part]) && schema.paths[path].$embeddedSchemaType) {
+        if (Array.isArray(branch[part]) && schema.paths[path].embeddedSchemaType) {
           for (let i = 0; i < branch[part].length; ++i) {
-            branch[part][i] = schema.paths[path].$embeddedSchemaType.applyGetters(
+            branch[part][i] = schema.paths[path].embeddedSchemaType.applyGetters(
               branch[part][i],
               self
             );
@@ -4323,8 +4419,8 @@ function applyGetters(self, json) {
  * Applies schema type transforms to `json`.
  *
  * @param {Document} self
- * @param {Object} json
- * @return {Object} `json`
+ * @param {object} json
+ * @return {object} `json`
  * @api private
  */
 
@@ -4340,8 +4436,8 @@ function applySchemaTypeTransforms(self, json) {
   for (const path of paths) {
     const schematype = schema.paths[path];
     const topLevelTransformFunction = schematype.options.transform ?? schematype.constructor?.defaultOptions?.transform;
-    const embeddedSchemaTypeTransformFunction = schematype.$embeddedSchemaType?.options?.transform
-      ?? schematype.$embeddedSchemaType?.constructor?.defaultOptions?.transform;
+    const embeddedSchemaTypeTransformFunction = schematype.embeddedSchemaType?.options?.transform
+      ?? schematype.embeddedSchemaType?.constructor?.defaultOptions?.transform;
     if (typeof topLevelTransformFunction === 'function') {
       const val = self.$get(path);
       if (val === undefined) {
@@ -4393,7 +4489,7 @@ function omitDeselectedFields(self, json) {
     selected = {};
     queryhelpers.applyPaths(selected, schema);
   }
-  if (selected == null || Object.keys(selected).length === 0) {
+  if (selected == null || utils.hasOwnKeys(selected) === false) {
     return json;
   }
 
@@ -4419,12 +4515,12 @@ function omitDeselectedFields(self, json) {
  *
  * See [schema options](https://mongoosejs.com/docs/guide.html#toJSON) for more information on setting `toJSON` option defaults.
  *
- * @param {Object} options
- * @param {Boolean} [options.flattenMaps=true] if true, convert Maps to [POJOs](https://masteringjs.io/tutorials/fundamentals/pojo). Useful if you want to `JSON.stringify()` the result.
- * @param {Boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
- * @param {Boolean} [options.flattenUUIDs=false] if true, convert any UUIDs in the result to 36-character UUID strings in 8-4-4-4-12 format.
- * @param {Boolean} [options.schemaFieldsOnly=false] - If true, the resulting object will only have fields that are defined in the document's schema. By default, `toJSON()` returns all fields in the underlying document from MongoDB, including ones that are not listed in the schema.
- * @return {Object}
+ * @param {object} options
+ * @param {boolean} [options.flattenMaps=true] if true, convert Maps to [POJOs](https://masteringjs.io/tutorials/fundamentals/pojo). Useful if you want to `JSON.stringify()` the result.
+ * @param {boolean} [options.flattenObjectIds=false] if true, convert any ObjectIds in the result to 24 character hex strings.
+ * @param {boolean} [options.flattenUUIDs=false] if true, convert any UUIDs in the result to 36-character UUID strings in 8-4-4-4-12 format.
+ * @param {boolean} [options.schemaFieldsOnly=false] - If true, the resulting object will only have fields that are defined in the document's schema. By default, `toJSON()` returns all fields in the underlying document from MongoDB, including ones that are not listed in the schema.
+ * @return {object}
  * @see Document#toObject https://mongoosejs.com/docs/api/document.html#Document.prototype.toObject()
  * @see JSON.stringify() in JavaScript https://thecodebarbarian.com/the-80-20-guide-to-json-stringify-in-javascript.html
  * @api public
@@ -4494,7 +4590,7 @@ Document.prototype.$__setParent = function $__setParent(parent) {
 /**
  * Helper for console.log
  *
- * @return {String}
+ * @return {string}
  * @api public
  * @method inspect
  * @memberOf Document
@@ -4528,7 +4624,7 @@ if (inspect.custom) {
 /**
  * Helper for console.log
  *
- * @return {String}
+ * @return {string}
  * @api public
  * @method toString
  * @memberOf Document
@@ -4551,7 +4647,7 @@ Document.prototype.toString = function() {
  * `deepEqual()`.
  *
  * @param {Document} [doc] a document to compare. If falsy, will always return "false".
- * @return {Boolean}
+ * @return {boolean}
  * @api public
  * @memberOf Document
  * @instance
@@ -4596,21 +4692,21 @@ Document.prototype.equals = function(doc) {
  *     await doc.populate('fans', '-email');
  *     doc.fans[0].email // undefined because of 2nd param `select`
  *
- * @param {String|Object|Array} path either the path to populate or an object specifying all parameters, or either an array of those
- * @param {Object|String} [select] Field selection for the population query
+ * @param {string|object|Array} path either the path to populate or an object specifying all parameters, or either an array of those
+ * @param {object|string} [select] Field selection for the population query
  * @param {Model} [model] The model you wish to use for population. If not specified, populate will look up the model by the name in the Schema's `ref` field.
- * @param {Object} [match] Conditions for the population query
- * @param {Object} [options] Options for the population query (sort, etc)
- * @param {String} [options.path=null] The path to populate.
+ * @param {object} [match] Conditions for the population query
+ * @param {object} [options] Options for the population query (sort, etc)
+ * @param {string} [options.path=null] The path to populate.
  * @param {string|PopulateOptions} [options.populate=null] Recursively populate paths in the populated documents. See [deep populate docs](https://mongoosejs.com/docs/populate.html#deep-populate).
  * @param {boolean} [options.retainNullValues=false] by default, Mongoose removes null and undefined values from populated arrays. Use this option to make `populate()` retain `null` and `undefined` array entries.
  * @param {boolean} [options.getters=false] if true, Mongoose will call any getters defined on the `localField`. By default, Mongoose gets the raw value of `localField`. For example, you would need to set this option to `true` if you wanted to [add a `lowercase` getter to your `localField`](https://mongoosejs.com/docs/schematypes.html#schematype-options).
  * @param {boolean} [options.clone=false] When you do `BlogPost.find().populate('author')`, blog posts with the same author will share 1 copy of an `author` doc. Enable this option to make Mongoose clone populated docs before assigning them.
- * @param {Object|Function} [options.match=null] Add an additional filter to the populate query. Can be a filter object containing [MongoDB query syntax](https://www.mongodb.com/docs/manual/tutorial/query-documents/), or a function that returns a filter object.
+ * @param {object|Function} [options.match=null] Add an additional filter to the populate query. Can be a filter object containing [MongoDB query syntax](https://www.mongodb.com/docs/manual/tutorial/query-documents/), or a function that returns a filter object.
  * @param {Function} [options.transform=null] Function that Mongoose will call on every populated document that allows you to transform the populated document.
- * @param {Object} [options.options=null] Additional options like `limit` and `lean`.
- * @param {Boolean} [options.forceRepopulate=true] Set to `false` to prevent Mongoose from repopulating paths that are already populated
- * @param {Boolean} [options.ordered=false] Set to `true` to execute any populate queries one at a time, as opposed to in parallel. We recommend setting this option to `true` if using transactions, especially if also populating multiple paths or paths with multiple models. MongoDB server does **not** support multiple operations in parallel on a single transaction.
+ * @param {object} [options.options=null] Additional options like `limit` and `lean`.
+ * @param {boolean} [options.forceRepopulate=true] Set to `false` to prevent Mongoose from repopulating paths that are already populated
+ * @param {boolean} [options.ordered=false] Set to `true` to execute any populate queries one at a time, as opposed to in parallel. We recommend setting this option to `true` if using transactions, especially if also populating multiple paths or paths with multiple models. MongoDB server does **not** support multiple operations in parallel on a single transaction.
  * @param {Function} [callback] Callback
  * @see population https://mongoosejs.com/docs/populate.html
  * @see Query#select https://mongoosejs.com/docs/api/query.html#Query.prototype.select()
@@ -4708,10 +4804,10 @@ Document.prototype.$getPopulatedDocs = function $getPopulatedDocs() {
  *
  * If the path was not populated, returns `undefined`.
  *
- * @param {String} path
- * @param {Any} [val]
- * @param {Object} [options]
- * @return {Array|ObjectId|Number|Buffer|String|undefined}
+ * @param {string} path
+ * @param {any} [val]
+ * @param {object} [options]
+ * @return {Array|ObjectId|number|Buffer|string|undefined}
  * @memberOf Document
  * @instance
  * @api public
@@ -4746,7 +4842,7 @@ Document.prototype.populated = function(path, val, options) {
   for (let i = 0; i < pieces.length - 1; ++i) {
     const subpath = pieces.slice(0, i + 1).join('.');
     const subdoc = this.$get(subpath);
-    if (subdoc != null && subdoc.$__ != null && this.$populated(subpath)) {
+    if (subdoc?.$__ != null && this.$populated(subpath)) {
       const rest = pieces.slice(i + 1).join('.');
       subdoc.$populated(rest, val, options);
       // No need to continue because the above recursion should take care of
@@ -4783,8 +4879,8 @@ Document.prototype.$populated = Document.prototype.populated;
  *     doc.$assertPopulated('likes', { likes });
  *
  *
- * @param {String|String[]} path path or array of paths to check. `$assertPopulated` throws if any of the given paths is not populated.
- * @param {Object} [values] optional values to `$set()`. Convenient if you want to manually populate a path and assert that the path was populated in 1 call.
+ * @param {string|string[]} path path or array of paths to check. `$assertPopulated` throws if any of the given paths is not populated.
+ * @param {object} [values] optional values to `$set()`. Convenient if you want to manually populate a path and assert that the path was populated in 1 call.
  * @return {Document} this
  * @memberOf Document
  * @method $assertPopulated
@@ -4822,7 +4918,7 @@ Document.prototype.$assertPopulated = function $assertPopulated(path, values) {
  *
  * If the path was not provided, then all populated fields are returned to their unpopulated state.
  *
- * @param {String|String[]} [path] Specific Path to depopulate. If unset, will depopulate all paths on the Document. Or multiple space-delimited paths.
+ * @param {string|string[]} [path] Specific Path to depopulate. If unset, will depopulate all paths on the Document. Or multiple space-delimited paths.
  * @return {Document} this
  * @see Document.populate https://mongoosejs.com/docs/api/document.html#Document.prototype.populate()
  * @api public
@@ -4837,7 +4933,7 @@ Document.prototype.depopulate = function(path) {
 
   let populatedIds;
   const virtualKeys = this.$$populatedVirtuals ? Object.keys(this.$$populatedVirtuals) : [];
-  const populated = this.$__ && this.$__.populated || {};
+  const populated = this.$__?.populated || {};
 
   if (arguments.length === 0) {
     // Depopulate all
@@ -4910,8 +5006,8 @@ Document.prototype.depopulate = function(path) {
 /**
  * Returns the full path to this document.
  *
- * @param {String} [path]
- * @return {String}
+ * @param {string} [path]
+ * @return {string}
  * @api private
  * @method $__fullPath
  * @memberOf Document
@@ -4942,51 +5038,103 @@ Document.prototype.$__fullPath = function(path) {
  *     });
  *
  *     // returns an empty object, no changes happened yet
- *     user.getChanges(); // { }
+ *     user.$getChanges(); // { }
  *
  *     user.country = undefined;
  *     user.age = 26;
  *
- *     user.getChanges(); // { $set: { age: 26 }, { $unset: { country: 1 } } }
+ *     user.$getChanges(); // { $set: { age: 26 }, { $unset: { country: 1 } } }
  *
  *     await user.save();
  *
- *     user.getChanges(); // { }
+ *     user.$getChanges(); // { }
  *
- * Modifying the object that `getChanges()` returns does not affect the document's
- * change tracking state. Even if you `delete user.getChanges().$set`, Mongoose
+ * Modifying the object that `$getChanges()` returns does not affect the document's
+ * change tracking state. Even if you `delete user.$getChanges().$set`, Mongoose
  * will still send a `$set` to the server.
  *
- * @return {Object}
+ * @return {object}
  * @api public
- * @method getChanges
+ * @method $getChanges
  * @memberOf Document
  * @instance
  */
 
-Document.prototype.getChanges = function() {
+Document.prototype.$getChanges = function() {
   const delta = this.$__delta();
   const changes = delta ? delta[1] : {};
   return changes;
 };
 
+/**
+ * **Deprecated.** Use `$getChanges()` instead.
+ *
+ * Returns the changes that happened to the document
+ * in the format that will be sent to MongoDB.
+ *
+ * @return {Object}
+ * @deprecated Use `$getChanges()` instead. `getChanges` does not use the `$` prefix convention and may conflict with user-defined schema methods/properties.
+ * @api public
+ * @method getChanges
+ * @memberOf Document
+ * @instance
+ */
+
+Document.prototype.getChanges = function() {
+  utils.warn('`getChanges()` is deprecated, use `$getChanges()` instead.');
+  return this.$getChanges();
+};
+
 /**
  * Produces a special query document of the modified properties used in updates.
  *
+ * @param {string[]|null} [pathsToSave] paths to include in delta generation
+ * @param {Set<string>|null} [pathsToSaveSet] pre-built Set of pathsToSave for O(1) exact lookup
  * @api private
  * @method $__delta
  * @memberOf Document
  * @instance
  */
 
-Document.prototype.$__delta = function $__delta() {
-  const dirty = this.$__dirty();
+Document.prototype.$__delta = function $__delta(pathsToSave, pathsToSaveSet) {
+  const allDirty = this.$__dirty();
+  let dirty = allDirty;
+  let unsavedDirty = null;
+  if (pathsToSave != null) {
+    dirty = [];
+    unsavedDirty = [];
+    for (const data of allDirty) {
+      if (isInPathsToSave(data.path, pathsToSaveSet, pathsToSave)) {
+        dirty.push(data);
+      } else {
+        unsavedDirty.push(data);
+      }
+    }
+  }
   const optimisticConcurrency = this.$__schema.options.optimisticConcurrency;
   if (optimisticConcurrency) {
     if (Array.isArray(optimisticConcurrency)) {
-      const optCon = new Set(optimisticConcurrency);
-      const modPaths = this.modifiedPaths();
-      if (modPaths.find(path => optCon.has(path))) {
+      if (!this.$__schema.options._optimisticConcurrencySet) {
+        this.$__schema.options._optimisticConcurrencySet = new Set(optimisticConcurrency);
+      }
+      const optimisticConcurrencySet = this.$__schema.options._optimisticConcurrencySet;
+      const modPaths = this.directModifiedPaths();
+      const hasRelevantModPaths = pathsToSave == null ?
+        modPaths.find(path => _pathOverlapsSet(path, optimisticConcurrencySet)) :
+        modPaths.find(path => _pathOverlapsSet(path, optimisticConcurrencySet) && isInPathsToSave(path, pathsToSaveSet, pathsToSave));
+      if (hasRelevantModPaths) {
+        this.$__.version = dirty.length ? VERSION_ALL : VERSION_WHERE;
+      }
+    } else if (Array.isArray(optimisticConcurrency?.exclude)) {
+      if (!this.$__schema.options._optimisticConcurrencyExcludeSet) {
+        this.$__schema.options._optimisticConcurrencyExcludeSet = new Set(optimisticConcurrency.exclude);
+      }
+      const optimisticConcurrencyExcludeSet = this.$__schema.options._optimisticConcurrencyExcludeSet;
+      const modPaths = this.directModifiedPaths();
+      const hasRelevantModPaths = pathsToSave == null ?
+        modPaths.find(path => !_pathOverlapsSet(path, optimisticConcurrencyExcludeSet)) :
+        modPaths.find(path => !_pathOverlapsSet(path, optimisticConcurrencyExcludeSet) && isInPathsToSave(path, pathsToSaveSet, pathsToSave));
+      if (hasRelevantModPaths) {
         this.$__.version = dirty.length ? VERSION_ALL : VERSION_WHERE;
       }
     } else {
@@ -5006,7 +5154,7 @@ Document.prototype.$__delta = function $__delta() {
   where._id = this._doc._id;
   // If `_id` is an object, need to depopulate, but also need to be careful
   // because `_id` can technically be null (see gh-6406)
-  if ((where && where._id && where._id.$__ || null) != null) {
+  if (where?._id?.$__ != null) {
     where._id = where._id.toObject({ transform: false, depopulate: true });
   }
   for (; d < len; ++d) {
@@ -5065,7 +5213,7 @@ Document.prototype.$__delta = function $__delta() {
       value = value.toObject();
       operand(this, where, delta, data, value);
     } else {
-      if (this.$__.primitiveAtomics && this.$__.primitiveAtomics[data.path] != null) {
+      if (this.$__.primitiveAtomics?.[data.path] != null) {
         const val = this.$__.primitiveAtomics[data.path];
         const op = firstKey(val);
         operand(this, where, delta, data, val[op], op);
@@ -5084,18 +5232,18 @@ Document.prototype.$__delta = function $__delta() {
   }
 
   if (divergent.length) {
-    return new DivergentArrayError(divergent);
+    throw new DivergentArrayError(divergent);
   }
 
   if (this.$__.version) {
     this.$__version(where, delta);
   }
 
-  if (Object.keys(delta).length === 0) {
-    return [where, null];
+  if (utils.hasOwnKeys(delta) === false) {
+    return [where, null, unsavedDirty];
   }
 
-  return [where, delta];
+  return [where, delta, unsavedDirty];
 };
 
 /**
@@ -5104,9 +5252,9 @@ Document.prototype.$__delta = function $__delta() {
  *
  * @see https://github.com/Automattic/mongoose/issues/1334
  * @param {Document} doc
- * @param {String} path
- * @param {Any} array
- * @return {String|undefined}
+ * @param {string} path
+ * @param {any} array
+ * @return {string|undefined}
  * @api private
  */
 
@@ -5136,14 +5284,14 @@ function checkDivergentArray(doc, path, array) {
   // elements of the array and potentially would overwrite data.
   const check = pop.options.match ||
       pop.options.options && Object.hasOwn(pop.options.options, 'limit') || // 0 is not permitted
-      pop.options.options && pop.options.options.skip || // 0 is permitted
+      pop.options.options?.skip || // 0 is permitted
       pop.options.select && // deselected _id?
       (pop.options.select._id === 0 ||
       /\s?-_id\s?/.test(pop.options.select));
 
   if (check) {
     const atomics = array[arrayAtomicsSymbol];
-    if (Object.keys(atomics).length === 0 || atomics.$set || atomics.$pop) {
+    if (utils.hasOwnKeys(atomics) === false || atomics.$set || atomics.$pop) {
       return path;
     }
   }
@@ -5154,11 +5302,11 @@ function checkDivergentArray(doc, path, array) {
  * well as track versioning for our where clause.
  *
  * @param {Document} self
- * @param {Object} where Unused
- * @param {Object} delta
- * @param {Object} data
+ * @param {object} where Unused
+ * @param {object} delta
+ * @param {object} data
  * @param {Mixed} val
- * @param {String} [op]
+ * @param {string} [op]
  * @api private
  */
 
@@ -5176,7 +5324,11 @@ function operand(self, where, delta, data, val, op) {
   // already marked for versioning?
   if (VERSION_ALL === (VERSION_ALL & self.$__.version)) return;
 
-  if (self.$__schema.options.optimisticConcurrency) {
+  if (
+    self.$__schema.options.optimisticConcurrency === true ||
+      Array.isArray(self.$__schema.options.optimisticConcurrency) ||
+      Array.isArray(self.$__schema.options.optimisticConcurrency?.exclude)
+  ) {
     return;
   }
 
@@ -5222,15 +5374,15 @@ function operand(self, where, delta, data, val, op) {
  * Compiles an update and where clause for a `val` with _atomics.
  *
  * @param {Document} self
- * @param {Object} where
- * @param {Object} delta
- * @param {Object} data
+ * @param {object} where
+ * @param {object} delta
+ * @param {object} data
  * @param {Array} value
  * @api private
  */
 
 function handleAtomics(self, where, delta, data, value) {
-  if (delta.$set && delta.$set[data.path]) {
+  if (delta.$set?.[data.path]) {
     // $set has precedence over other atomics
     return;
   }
@@ -5303,8 +5455,8 @@ function handleAtomics(self, where, delta, data, value) {
  * Determines whether versioning should be skipped for the given path
  *
  * @param {Document} self
- * @param {String} path
- * @return {Boolean} true if versioning should be skipped for the given path
+ * @param {string} path
+ * @return {boolean} true if versioning should be skipped for the given path
  * @api private
  */
 function shouldSkipVersioning(self, path) {
@@ -5343,7 +5495,10 @@ Document.prototype.$clone = function() {
       }
       clonedCache[key] = clone(this.$__[key]);
     }
-    Object.assign(clonedCache.activePaths, clone({ ...this.$__.activePaths }));
+    Object.assign(
+      clonedCache.activePaths,
+      clone({ ...this.$__.activePaths })
+    );
     clonedDoc.$__ = clonedCache;
   }
   return clonedDoc;
@@ -5505,6 +5660,32 @@ Document.prototype._applyVersionIncrement = function _applyVersionIncrement() {
  * Module exports.
  */
 
+/*!
+ * Check if `path`, any of its ancestor paths, or any of its descendant paths
+ * exist in `pathSet`.
+ * For example:
+ *   _pathOverlapsSet('profile.firstName', Set(['profile'])) === true
+ *   _pathOverlapsSet('profile', Set(['profile.firstName'])) === true
+ */
+function _pathOverlapsSet(path, pathSet) {
+  if (pathSet.has(path)) {
+    return true;
+  }
+  let idx = path.indexOf('.');
+  while (idx !== -1) {
+    if (pathSet.has(path.substring(0, idx))) {
+      return true;
+    }
+    idx = path.indexOf('.', idx + 1);
+  }
+  for (const p of pathSet) {
+    if (p.length > path.length + 1 && p[path.length] === '.' && p.slice(0, path.length) === path) {
+      return true;
+    }
+  }
+  return false;
+}
+
 Document.VERSION_WHERE = VERSION_WHERE;
 Document.VERSION_INC = VERSION_INC;
 Document.VERSION_ALL = VERSION_ALL;