mongoose 9.2.3 → 9.2.4

package/lib/schema.js

@@ -98,8 +98,8 @@ const numberRE = /^\d+$/;
  *
  * _When nesting schemas, (`children` in the example above), always declare the child schema first before passing it into its parent._
  *
- * @param {Object|Schema|Array} [definition] Can be one of: object describing schema paths, or schema to copy, or array of objects and schemas
- * @param {Object} [options]
+ * @param {object|Schema|Array} [definition] Can be one of: object describing schema paths, or schema to copy, or array of objects and schemas
+ * @param {object} [options]
  * @inherits NodeJS EventEmitter https://nodejs.org/api/events.html#class-eventemitter
  * @event `init`: Emitted after the schema is compiled into a `Model`.
  * @api public
@@ -385,8 +385,8 @@ Schema.prototype.tree;
  *     // Equivalent:
  *     const schema2 = new Schema({ name: String }, { toObject: { virtuals: true } });
  *
- * @param {Object} definition
- * @param {Object} [options]
+ * @param {object} definition
+ * @param {object} [options]
  * @return {Schema} the new schema
  * @api public
  * @memberOf Schema
@@ -510,8 +510,8 @@ Schema.prototype._clone = function _clone(Constructor) {
  *     newSchema.path('name'); // SchemaString { ... }
  *     newSchema.path('age'); // undefined
  *
- * @param {String[]} paths List of Paths to pick for the new Schema
- * @param {Object} [options] Options to pass to the new Schema Constructor (same as `new Schema(.., Options)`). Defaults to `this.options` if not set.
+ * @param {string[]} paths List of Paths to pick for the new Schema
+ * @param {object} [options] Options to pass to the new Schema Constructor (same as `new Schema(.., Options)`). Defaults to `this.options` if not set.
  * @return {Schema}
  * @api public
  */
@@ -565,8 +565,8 @@ Schema.prototype.pick = function(paths, options) {
  *     newSchema.path('name'); // SchemaString { ... }
  *     newSchema.path('age'); // undefined
  *
- * @param {String[]} paths List of Paths to omit for the new Schema
- * @param {Object} [options] Options to pass to the new Schema Constructor (same as `new Schema(.., Options)`). Defaults to `this.options` if not set.
+ * @param {string[]} paths List of Paths to omit for the new Schema
+ * @param {object} [options] Options to pass to the new Schema Constructor (same as `new Schema(.., Options)`). Defaults to `this.options` if not set.
  * @return {Schema}
  * @api public
  */
@@ -596,8 +596,8 @@ Schema.prototype.omit = function(paths, options) {
 /**
  * Returns default options for this schema, merged with `options`.
  *
- * @param {Object} [options] Options to overwrite the default options
- * @return {Object} The merged options of `options` and the default options
+ * @param {object} [options] Options to overwrite the default options
+ * @return {object} The merged options of `options` and the default options
  * @api private
  */
 
@@ -672,14 +672,14 @@ Schema.prototype.defaultOptions = function(options) {
  *     doc.element; // '#hero'
  *     doc instanceof ClickedModel; // true
  *
- * @param {String} name the name of the discriminator
+ * @param {string} name the name of the discriminator
  * @param {Schema} schema the discriminated Schema
- * @param {Object} [options] discriminator options
- * @param {String} [options.value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
- * @param {Boolean} [options.clone=true] By default, `discriminator()` clones the given `schema`. Set to `false` to skip cloning.
- * @param {Boolean} [options.overwriteModels=false] by default, Mongoose does not allow you to define a discriminator with the same name as another discriminator. Set this to allow overwriting discriminators with the same name.
- * @param {Boolean} [options.mergeHooks=true] By default, Mongoose merges the base schema's hooks with the discriminator schema's hooks. Set this option to `false` to make Mongoose use the discriminator schema's hooks instead.
- * @param {Boolean} [options.mergePlugins=true] By default, Mongoose merges the base schema's plugins with the discriminator schema's plugins. Set this option to `false` to make Mongoose use the discriminator schema's plugins instead.
+ * @param {object} [options] discriminator options
+ * @param {string} [options.value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
+ * @param {boolean} [options.clone=true] By default, `discriminator()` clones the given `schema`. Set to `false` to skip cloning.
+ * @param {boolean} [options.overwriteModels=false] by default, Mongoose does not allow you to define a discriminator with the same name as another discriminator. Set this to allow overwriting discriminators with the same name.
+ * @param {boolean} [options.mergeHooks=true] By default, Mongoose merges the base schema's hooks with the discriminator schema's hooks. Set this option to `false` to make Mongoose use the discriminator schema's hooks instead.
+ * @param {boolean} [options.mergePlugins=true] By default, Mongoose merges the base schema's plugins with the discriminator schema's plugins. Set this option to `false` to make Mongoose use the discriminator schema's plugins instead.
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -768,8 +768,8 @@ Schema.prototype.encryptionType = function encryptionType(encryptionType) {
  *     // getters, setters, indexes, methods, and statics.
  *     TurboManSchema.add(ToySchema).add({ year: Number });
  *
- * @param {Object|Schema} obj plain object with paths to add, or another schema
- * @param {String} [prefix] path to prefix the newly added paths with
+ * @param {object|Schema} obj plain object with paths to add, or another schema
+ * @param {string} [prefix] path to prefix the newly added paths with
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -1073,8 +1073,8 @@ Schema.prototype._buildSchemaMap = function() {
  *     await turboMan.save(); // Saves { _id: ..., n: 'Turbo Man Action Figure' }
  *
  *
- * @param {String} path real path to alias
- * @param {String|String[]} alias the path(s) to use as an alias for `path`
+ * @param {string} path real path to alias
+ * @param {string|string[]} alias the path(s) to use as an alias for `path`
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -1106,7 +1106,7 @@ Schema.prototype.alias = function alias(path, alias) {
  *     // Remove index by name
  *     ToySchema.removeIndex('my custom index name');
  *
- * @param {Object|string} index name or index specification
+ * @param {object|string} index name or index specification
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -1173,9 +1173,9 @@ Schema.prototype.clearIndexes = function clearIndexes() {
  *     const ToySchema = new Schema({ name: String, color: String, price: Number });
  *     ToySchema.searchIndex({ name: 'test', definition: { mappings: { dynamic: true } } });
  *
- * @param {Object} description index options, including `name` and `definition`
- * @param {String} description.name
- * @param {Object} description.definition
+ * @param {object} description index options, including `name` and `definition`
+ * @param {string} description.name
+ * @param {object} description.definition
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -1261,8 +1261,8 @@ reserved.collection = 1;
  *     schema.path('name') // returns a SchemaType
  *     schema.path('name', Number) // changes the schemaType of `name` to Number
  *
- * @param {String} path The name of the Path to get / set
- * @param {Object} [obj] The Type to set the path to, if provided the path will be SET, otherwise the path will be GET
+ * @param {string} path The name of the Path to get / set
+ * @param {object} [obj] The Type to set the path to, if provided the path will be SET, otherwise the path will be GET
  * @api public
  */
 
@@ -1571,9 +1571,9 @@ Object.defineProperty(Schema.prototype, 'base', {
 /**
  * Converts type arguments into Mongoose Types.
  *
- * @param {String} path
- * @param {Object} obj constructor
- * @param {Object} options schema options
+ * @param {string} path
+ * @param {object} obj constructor
+ * @param {object} options schema options
  * @api private
  */
 
@@ -1840,7 +1840,7 @@ Schema.prototype.eachPath = function(fn) {
  *     s.requiredPaths(); // [ 'age', 'name' ]
  *
  * @api public
- * @param {Boolean} invalidate Refresh the cache
+ * @param {boolean} invalidate Refresh the cache
  * @return {Array}
  */
 
@@ -1892,8 +1892,8 @@ Schema.prototype.indexedPaths = function indexedPaths() {
  *     s.pathType('foo'); // "virtual"
  *     s.pathType('fail'); // "adhocOrUndefined"
  *
- * @param {String} path
- * @return {String}
+ * @param {string} path
+ * @return {string}
  * @api public
  */
 
@@ -1935,8 +1935,8 @@ Schema.prototype.pathType = function(path) {
 /**
  * Returns true iff this path is a child of a mixed schema.
  *
- * @param {String} path
- * @return {Boolean}
+ * @param {string} path
+ * @return {boolean}
  * @api private
  */
 
@@ -1957,7 +1957,7 @@ Schema.prototype.hasMixedParent = function(path) {
 /**
  * Setup updatedAt and createdAt timestamps to documents if enabled
  *
- * @param {Boolean|Object} timestamps timestamps options
+ * @param {boolean|object} timestamps timestamps options
  * @api private
  */
 Schema.prototype.setupTimestamp = function(timestamps) {
@@ -1966,8 +1966,8 @@ Schema.prototype.setupTimestamp = function(timestamps) {
 
 /**
  * ignore. Deprecated re: #6405
- * @param {Any} self
- * @param {String} path
+ * @param {any} self
+ * @param {string} path
  * @api private
  */
 
@@ -2053,7 +2053,7 @@ function getPositionalPath(self, path, cleanPath) {
  *     const Model = mongoose.model('Test', schema);
  *     new Model({ name: 'test' }); // Prints '{"_id": ..., "name": "test" }'
  *
- * @param {String} name name of the document method to call later
+ * @param {string} name name of the document method to call later
  * @param {Array} args arguments to pass to the method
  * @api public
  */
@@ -2096,10 +2096,10 @@ Schema.prototype.queue = function(name, args) {
  *       // Runs when you call `doc.deleteOne()`
  *     });
  *
- * @param {String|RegExp|String[]} methodName The method name or regular expression to match method name
- * @param {Object} [options]
- * @param {Boolean} [options.document] If `name` is a hook for both document and query middleware, set to `true` to run on document middleware. For example, set `options.document` to `true` to apply this hook to `Document#deleteOne()` rather than `Query#deleteOne()`.
- * @param {Boolean} [options.query] If `name` is a hook for both document and query middleware, set to `true` to run on query middleware.
+ * @param {string|RegExp|string[]} methodName The method name or regular expression to match method name
+ * @param {object} [options]
+ * @param {boolean} [options.document] If `name` is a hook for both document and query middleware, set to `true` to run on document middleware. For example, set `options.document` to `true` to apply this hook to `Document#deleteOne()` rather than `Query#deleteOne()`.
+ * @param {boolean} [options.query] If `name` is a hook for both document and query middleware, set to `true` to run on query middleware.
  * @param {Function} callback
  * @api public
  */
@@ -2150,10 +2150,10 @@ Schema.prototype.pre = function(name) {
  *     await m.find();
  *     console.log('this fires after the post find hook');
  *
- * @param {String|RegExp|String[]} methodName The method name or regular expression to match method name
- * @param {Object} [options]
- * @param {Boolean} [options.document] If `name` is a hook for both document and query middleware, set to `true` to run on document middleware.
- * @param {Boolean} [options.query] If `name` is a hook for both document and query middleware, set to `true` to run on query middleware.
+ * @param {string|RegExp|string[]} methodName The method name or regular expression to match method name
+ * @param {object} [options]
+ * @param {boolean} [options.document] If `name` is a hook for both document and query middleware, set to `true` to run on document middleware.
+ * @param {boolean} [options.query] If `name` is a hook for both document and query middleware, set to `true` to run on query middleware.
  * @param {Function} fn callback
  * @see middleware https://mongoosejs.com/docs/middleware.html
  * @see kareem https://npmjs.org/package/kareem
@@ -2197,8 +2197,8 @@ Schema.prototype.post = function(name) {
  *     mongoose.model('Test', s); // Prints 'Schema Path Name: name'
  *
  * @param {Function} plugin The Plugin's callback
- * @param {Object} [opts] Options to pass to the plugin
- * @param {Boolean} [opts.deduplicate=false] If true, ignore duplicate plugins (same `fn` argument using `===`)
+ * @param {object} [opts] Options to pass to the plugin
+ * @param {boolean} [opts.deduplicate=false] If true, ignore duplicate plugins (same `fn` argument using `===`)
  * @see plugins https://mongoosejs.com/docs/plugins.html
  * @api public
  */
@@ -2253,7 +2253,7 @@ Schema.prototype.plugin = function(fn, opts) {
  *
  * NOTE: `Schema.method()` adds instance methods to the `Schema.methods` object. You can also add instance methods directly to the `Schema.methods` object as seen in the [guide](https://mongoosejs.com/docs/guide.html#methods)
  *
- * @param {String|Object} name The Method Name for a single function, or a Object of "string-function" pairs.
+ * @param {string|object} name The Method Name for a single function, or a Object of "string-function" pairs.
  * @param {Function} [fn] The Function in a single-function definition.
  * @api public
  */
@@ -2298,7 +2298,7 @@ Schema.prototype.method = function(name, fn, options) {
  *
  * If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.
  *
- * @param {String|Object} name The Method Name for a single function, or a Object of "string-function" pairs.
+ * @param {string|object} name The Method Name for a single function, or a Object of "string-function" pairs.
  * @param {Function} [fn] The Function in a single-function definition.
  * @api public
  * @see Statics https://mongoosejs.com/docs/guide.html#statics
@@ -2322,10 +2322,10 @@ Schema.prototype.static = function(name, fn) {
  *
  *     schema.index({ first: 1, last: -1 })
  *
- * @param {Object} fields The Fields to index, with the order, available values: `1 | -1 | '2d' | '2dsphere' | 'geoHaystack' | 'hashed' | 'text'`
- * @param {Object} [options] Options to pass to [MongoDB driver's `createIndex()` function](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#createIndex)
- * @param {String | number} [options.expires=null] Mongoose-specific syntactic sugar, uses [ms](https://www.npmjs.com/package/ms) to convert `expires` option into seconds for the `expireAfterSeconds` in the above link.
- * @param {String} [options.language_override=null] Tells mongodb to use the specified field instead of `language` for parsing text indexes.
+ * @param {object} fields The Fields to index, with the order, available values: `1 | -1 | '2d' | '2dsphere' | 'geoHaystack' | 'hashed' | 'text'`
+ * @param {object} [options] Options to pass to [MongoDB driver's `createIndex()` function](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#createIndex)
+ * @param {string | number} [options.expires=null] Mongoose-specific syntactic sugar, uses [ms](https://www.npmjs.com/package/ms) to convert `expires` option into seconds for the `expireAfterSeconds` in the above link.
+ * @param {string} [options.language_override=null] Tells mongodb to use the specified field instead of `language` for parsing text indexes.
  * @api public
  */
 
@@ -2362,9 +2362,9 @@ Schema.prototype.index = function(fields, options) {
  *     schema.set('strict', false); // Sets 'strict' to false
  *     schema.set('strict'); // 'false'
  *
- * @param {String} key The name of the option to set the value to
- * @param {Object} [value] The value to set the option to, if not passed, the option will be reset to default
- * @param {Array<string>} [tags] tags to add to read preference if key === 'read'
+ * @param {string} key The name of the option to set the value to
+ * @param {object} [value] The value to set the option to, if not passed, the option will be reset to default
+ * @param {string[]} [tags] tags to add to read preference if key === 'read'
  * @see Schema https://mongoosejs.com/docs/api/schema.html#Schema()
  * @api public
  */
@@ -2455,9 +2455,9 @@ function _propagateOptionsToImplicitlyCreatedSchemas(baseSchema, options) {
  *     schema.set('strict', false);
  *     schema.get('strict'); // false
  *
- * @param {String} key The name of the Option to get the current value for
+ * @param {string} key The name of the Option to get the current value for
  * @api public
- * @return {Any} the option's value
+ * @return {any} the option's value
  */
 
 Schema.prototype.get = function(key) {
@@ -2469,7 +2469,7 @@ const indexTypes = '2d 2dsphere hashed text'.split(' ');
 /**
  * The allowed index types
  *
- * @property {String[]} indexTypes
+ * @property {string[]} indexTypes
  * @memberOf Schema
  * @static
  * @api public
@@ -2521,16 +2521,16 @@ Schema.prototype.indexes = function() {
 /**
  * Creates a virtual type with the given name.
  *
- * @param {String} name The name of the Virtual
- * @param {Object} [options]
- * @param {String|Model} [options.ref] model name or model instance. Marks this as a [populate virtual](https://mongoosejs.com/docs/populate.html#populate-virtuals).
- * @param {String|Function} [options.localField] Required for populate virtuals. See [populate virtual docs](https://mongoosejs.com/docs/populate.html#populate-virtuals) for more information.
- * @param {String|Function} [options.foreignField] Required for populate virtuals. See [populate virtual docs](https://mongoosejs.com/docs/populate.html#populate-virtuals) for more information.
- * @param {Boolean|Function} [options.justOne=false] Only works with populate virtuals. If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), will be a single doc or `null`. Otherwise, the populate virtual will be an array.
- * @param {Boolean} [options.count=false] Only works with populate virtuals. If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), this populate virtual will contain the number of documents rather than the documents themselves when you `populate()`.
+ * @param {string} name The name of the Virtual
+ * @param {object} [options]
+ * @param {string|Model} [options.ref] model name or model instance. Marks this as a [populate virtual](https://mongoosejs.com/docs/populate.html#populate-virtuals).
+ * @param {string|Function} [options.localField] Required for populate virtuals. See [populate virtual docs](https://mongoosejs.com/docs/populate.html#populate-virtuals) for more information.
+ * @param {string|Function} [options.foreignField] Required for populate virtuals. See [populate virtual docs](https://mongoosejs.com/docs/populate.html#populate-virtuals) for more information.
+ * @param {boolean|Function} [options.justOne=false] Only works with populate virtuals. If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), will be a single doc or `null`. Otherwise, the populate virtual will be an array.
+ * @param {boolean} [options.count=false] Only works with populate virtuals. If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), this populate virtual will contain the number of documents rather than the documents themselves when you `populate()`.
  * @param {Function|null} [options.get=null] Adds a [getter](https://mongoosejs.com/docs/tutorials/getters-setters.html) to this virtual to transform the populated doc.
- * @param {Object|Function} [options.match=null] Apply a default [`match` option to populate](https://mongoosejs.com/docs/populate.html#match), adding an additional filter to the populate query.
- * @param {Boolean} [options.applyToArray=false] If true and the given `name` is a direct child of an array, apply the virtual to the array rather than the elements.
+ * @param {object|Function} [options.match=null] Apply a default [`match` option to populate](https://mongoosejs.com/docs/populate.html#match), adding an additional filter to the populate query.
+ * @param {boolean} [options.applyToArray=false] If true and the given `name` is a direct child of an array, apply the virtual to the array rather than the elements.
  * @return {VirtualType}
  */
 
@@ -2668,7 +2668,7 @@ Schema.prototype.virtual = function(name, options) {
 /**
  * Returns the virtual type with the given `name`.
  *
- * @param {String} name The name of the Virtual to get
+ * @param {string} name The name of the Virtual to get
  * @return {VirtualType|null}
  */
 
@@ -2692,7 +2692,7 @@ Schema.prototype.virtualpath = function(name) {
  *     schema.path('name'); // Undefined
  *     schema.path('age'); // Undefined
  *
- * @param {String|Array} path The Path(s) to remove
+ * @param {string|Array} path The Path(s) to remove
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -2750,7 +2750,7 @@ function _deletePath(schema, name) {
 /**
  * Removes the given virtual or virtuals from the schema.
  *
- * @param {String|Array} path The virutal path(s) to remove.
+ * @param {string|Array} path The virutal path(s) to remove.
  * @returns {Schema} the Schema instance, or a mongoose error if the virtual does not exist.
  * @api public
  */
@@ -2815,7 +2815,7 @@ Schema.prototype.removeVirtual = function(path) {
  * ```
  *
  * @param {Function} model The Class to load
- * @param {Boolean} [virtualsOnly] if truthy, only pulls virtuals from the class, not methods or statics
+ * @param {boolean} [virtualsOnly] if truthy, only pulls virtuals from the class, not methods or statics
  */
 Schema.prototype.loadClass = function(model, virtualsOnly) {
   // Stop copying when hit certain base classes
@@ -3109,8 +3109,8 @@ Schema.prototype._preCompile = function _preCompile() {
  *    // { required: ['_id'], properties: { name: { bsonType: ['string', 'null'] }, _id: { bsonType: 'objectId' } } }
  *    schema.toJSONSchema({ useBsonType: true });
  *
- * @param {Object} [options]
- * @param [Boolean] [options.useBsonType=false] if true, specify each path's type using `bsonType` rather than `type` for MongoDB $jsonSchema support
+ * @param {object} [options]
+ * @param {boolean} [options.useBsonType=false] if true, specify each path's type using `bsonType` rather than `type` for MongoDB $jsonSchema support
  */
 
 Schema.prototype.toJSONSchema = function toJSONSchema(options) {