mongoose 9.2.2 → 9.2.4

package/lib/document.js

@@ -77,11 +77,11 @@ 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 {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.
+ * @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
@@ -549,11 +549,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
@@ -637,9 +637,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
@@ -679,7 +679,7 @@ Document.prototype.$init = function() {
  * Internal "init" function
  *
  * @param {Document} doc
- * @param {Object} [opts]
+ * @param {object} [opts]
  * @returns {Document} this
  * @api private
  */
@@ -732,12 +732,12 @@ 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
  */
 
@@ -859,14 +859,14 @@ 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|'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
+ * @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
@@ -911,8 +911,8 @@ Document.prototype.updateOne = function updateOne(update, options) {
  *  - 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
@@ -993,7 +993,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
@@ -1026,7 +1026,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
@@ -1061,11 +1061,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
@@ -1629,10 +1629,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
@@ -1646,14 +1646,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
@@ -1710,14 +1710,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
@@ -1821,8 +1821,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
  */
 
@@ -1854,8 +1854,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
  */
 
@@ -1912,8 +1912,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
  */
@@ -1934,12 +1934,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
  */
 
@@ -2031,7 +2031,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
@@ -2060,7 +2060,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
  */
@@ -2100,7 +2100,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
  */
 
@@ -2123,7 +2123,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
  */
 
@@ -2150,7 +2150,7 @@ Document.prototype.$ignore = function(path) {
  *     doc.directModifiedPaths(); // ['nested.bar']
  *     doc.modifiedPaths(); // ['nested', 'nested.bar']
  *
- * @return {String[]}
+ * @return {string[]}
  * @api public
  */
 
@@ -2175,12 +2175,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) {
@@ -2230,9 +2230,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
  */
 
@@ -2311,10 +2311,10 @@ 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
  */
 
@@ -2385,8 +2385,8 @@ Document.prototype[documentIsModified] = Document.prototype.isModified;
  * @memberOf Document
  * @instance
  * @method $isDefault
- * @param {String} [path]
- * @return {Boolean}
+ * @param {string} [path]
+ * @return {boolean}
  * @api public
  */
 
@@ -2421,8 +2421,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
@@ -2447,8 +2447,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
  */
 
@@ -2486,8 +2486,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
  */
 
@@ -2517,8 +2517,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
  */
 
@@ -2599,8 +2599,8 @@ Document.prototype.$__isSelected = Document.prototype.isSelected;
  *        doc.isDirectSelected('nested')  // false
  *     })
  *
- * @param {String} path
- * @return {Boolean}
+ * @param {string} path
+ * @return {boolean}
  * @api public
  */
 
@@ -2661,13 +2661,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
+ * @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
  */
@@ -3254,12 +3254,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
+ * @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
  */
@@ -3407,10 +3407,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
  */
@@ -3444,7 +3444,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
@@ -3522,16 +3522,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
@@ -3544,7 +3544,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
@@ -3778,7 +3778,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
@@ -3871,7 +3871,7 @@ Document.prototype.$__handleReject = function handleReject(err) {
 /**
  * Internal common logic for toObject() and toJSON()
  *
- * @return {Object}
+ * @return {object}
  * @api private
  * @method $toObject
  * @memberOf Document
@@ -4179,20 +4179,20 @@ 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.
+ * @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
  * @api public
  * @memberOf Document
@@ -4291,8 +4291,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
  */
 
@@ -4363,8 +4363,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
  */
 
@@ -4459,12 +4459,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
@@ -4534,7 +4534,7 @@ Document.prototype.$__setParent = function $__setParent(parent) {
 /**
  * Helper for console.log
  *
- * @return {String}
+ * @return {string}
  * @api public
  * @method inspect
  * @memberOf Document
@@ -4568,7 +4568,7 @@ if (inspect.custom) {
 /**
  * Helper for console.log
  *
- * @return {String}
+ * @return {string}
  * @api public
  * @method toString
  * @memberOf Document
@@ -4591,7 +4591,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
@@ -4636,21 +4636,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()
@@ -4748,10 +4748,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
@@ -4823,8 +4823,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
@@ -4862,7 +4862,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
@@ -4950,8 +4950,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
@@ -4997,7 +4997,7 @@ Document.prototype.$__fullPath = function(path) {
  * 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
  * @memberOf Document
@@ -5171,9 +5171,9 @@ Document.prototype.$__delta = function $__delta(pathsToSave, pathsToSaveSet) {
  *
  * @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
  */
 
@@ -5221,11 +5221,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
  */
 
@@ -5293,9 +5293,9 @@ 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
  */
@@ -5374,8 +5374,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) {