mongoose 6.4.3 → 6.4.6

package/lib/schema/buffer.js

@@ -60,8 +60,8 @@ SchemaBuffer._checkRequired = v => !!(v && v.length);
  *     const User = mongoose.model('User', new Schema({ test: Buffer }));
  *     new User({ }).validateSync().errors.test.message; // Path `test` is required.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema/date.js

@@ -60,8 +60,8 @@ SchemaDate._cast = castDate;
  *     const User = mongoose.model('User', new Schema({ test: Date }));
  *     new User({ }).validateSync().errors.test.message; // Path `test` is required.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema/decimal128.js

@@ -56,8 +56,8 @@ Decimal128._cast = castDecimal128;
  *     const User = mongoose.model('User', new Schema({ test: mongoose.Decimal128 }));
  *     new User({ }).validateSync().errors.test.message; // Path `test` is required.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema/documentarray.js

@@ -536,9 +536,9 @@ DocumentArrayPath.prototype.applyGetters = function(value, scope) {
  * Scopes paths selected in a query to this array.
  * Necessary for proper default application of subdocument values.
  *
- * @param {DocumentArrayPath} array - the array to scope `fields` paths
- * @param {Object|undefined} fields - the root fields selected in the query
- * @param {Boolean|undefined} init - if we are being created part of a query result
+ * @param {DocumentArrayPath} array the array to scope `fields` paths
+ * @param {Object|undefined} fields the root fields selected in the query
+ * @param {Boolean|undefined} init if we are being created part of a query result
  */
 
 function scopePaths(array, fields, init) {
@@ -572,6 +572,12 @@ function scopePaths(array, fields, init) {
   return hasKeys && selected || undefined;
 }
 
+/*!
+ * ignore
+ */
+
+DocumentArrayPath.defaultOptions = {};
+
 /**
  * Sets a default option for all DocumentArray instances.
  *
@@ -580,16 +586,14 @@ function scopePaths(array, fields, init) {
  *     // Make all numbers have option `min` equal to 0.
  *     mongoose.Schema.DocumentArray.set('_id', false);
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
- * @return {undefined}
+ * @param {String} option The name of the option you'd like to set (e.g. trim, lowercase, etc...)
+ * @param {Any} value The value of the option you'd like to set.
+ * @return {void}
  * @function set
  * @static
  * @api public
  */
 
-DocumentArrayPath.defaultOptions = {};
-
 DocumentArrayPath.set = SchemaType.set;
 
 /*!

package/lib/schema/mixed.js

@@ -84,8 +84,8 @@ Mixed.get = SchemaType.get;
  *     const User = mongoose.model('User', new Schema({ test: mongoose.Mixed }));
  *     new User({ }).validateSync().errors.test.message; // Path `test` is required.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema/number.js

@@ -57,8 +57,8 @@ SchemaNumber.get = SchemaType.get;
  *     const Order = mongoose.model('Order', new Schema({ amount: Number }));
  *     new Order({ amount: -10 }).validateSync().errors.amount.message; // Path `amount` must be larger than 0.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema/objectid.js

@@ -84,8 +84,8 @@ ObjectId.get = SchemaType.get;
  *     const Order = mongoose.model('Order', new Schema({ userId: ObjectId }));
  *     new Order({ }).validateSync().errors.userId.message; // Path `userId` is required.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema/string.js

@@ -133,8 +133,8 @@ SchemaString.get = SchemaType.get;
  *     const User = mongoose.model('User', new Schema({ name: String }));
  *     new User({ name: '   John Doe   ' }).name; // 'John Doe'
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static

package/lib/schema.js

@@ -79,6 +79,7 @@ let id = 0;
  * - [pluginTags](/docs/guide.html#pluginTags): array of strings - defaults to `undefined`. If set and plugin called with `tags` option, will only apply that plugin to schemas with a matching tag.
  *
  * #### Options for Nested Schemas:
+ *
  * - `excludeIndexes`: bool - defaults to `false`. If `true`, skip building indexes on this schema's paths.
  *
  * #### Note:
@@ -233,6 +234,7 @@ Object.defineProperty(Schema.prototype, 'childSchemas', {
  * You do not need to interact with this property at all to use mongoose.
  *
  * #### Example:
+ *
  *     const schema = new Schema({});
  *     schema.virtual('answer').get(() => 42);
  *
@@ -272,6 +274,7 @@ Schema.prototype.obj;
  * in this schema, and the values are instances of the SchemaType class.
  *
  * #### Example:
+ *
  *     const schema = new Schema({ name: String }, { _id: false });
  *     schema.paths; // { name: SchemaString { ... } }
  *
@@ -290,6 +293,7 @@ Schema.prototype.paths;
  * Schema as a tree
  *
  * #### Example:
+ *
  *     {
  *         '_id'     : ObjectId
  *       , 'nested'  : {
@@ -395,8 +399,8 @@ Schema.prototype._clone = function _clone(Constructor) {
  *     newSchema.path('name'); // SchemaString { ... }
  *     newSchema.path('age'); // undefined
  *
- * @param {Array} paths list of paths to pick
- * @param {Object} [options] options to pass to the schema constructor. 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
  */
@@ -426,8 +430,8 @@ Schema.prototype.pick = function(paths, options) {
 /**
  * Returns default options for this schema, merged with `options`.
  *
- * @param {Object} options
- * @return {Object}
+ * @param {Object} [options] Options to overwrite the default options
+ * @return {Object} The merged options of `options` and the default options
  * @api private
  */
 
@@ -550,6 +554,10 @@ Schema.prototype.add = function add(obj, prefix) {
   const keys = Object.keys(obj);
   const typeKey = this.options.typeKey;
   for (const key of keys) {
+    if (utils.specialProperties.has(key)) {
+      continue;
+    }
+
     const fullPath = prefix + key;
     const val = obj[key];
 
@@ -755,6 +763,10 @@ Schema.prototype.clearIndexes = function clearIndexes() {
  *
  *      const schema = new Schema(..);
  *      schema.methods.init = function () {} // potentially breaking
+ *
+ * @property reserved
+ * @memberOf Schema
+ * @static
  */
 
 Schema.reserved = Object.create(null);
@@ -788,13 +800,13 @@ reserved.collection = 1;
  * Sets a path (if arity 2)
  * Gets a path (if arity 1)
  *
- * #### Example
+ * #### Example:
  *
  *     schema.path('name') // returns a SchemaType
  *     schema.path('name', Number) // changes the schemaType of `name` to Number
  *
- * @param {String} path
- * @param {Object} constructor
+ * @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
  */
 
@@ -846,6 +858,9 @@ Schema.prototype.path = function(path, obj) {
   let fullPath = '';
 
   for (const sub of subpaths) {
+    if (utils.specialProperties.has(sub)) {
+      throw new Error('Cannot set special property `' + sub + '` on a schema');
+    }
     fullPath = fullPath += (fullPath.length > 0 ? '.' : '') + sub;
     if (!branch[sub]) {
       this.nested[fullPath] = true;
@@ -1059,6 +1074,7 @@ Object.defineProperty(Schema.prototype, 'base', {
  *
  * @param {String} path
  * @param {Object} obj constructor
+ * @param {Object} options
  * @api private
  */
 
@@ -1316,6 +1332,7 @@ Schema.prototype.eachPath = function(fn) {
  * Returns an Array of path strings that are required by this schema.
  *
  * #### Example:
+ *
  *     const s = new Schema({
  *       name: { type: String, required: true },
  *       age: { type: String, required: true },
@@ -1324,7 +1341,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}
  */
 
@@ -1545,7 +1562,7 @@ Schema.prototype.queue = function(name, args) {
 /**
  * Defines a pre hook for the model.
  *
- * #### Example
+ * #### Example:
  *
  *     const toySchema = new Schema({ name: String, created: Date });
  *
@@ -1577,7 +1594,7 @@ Schema.prototype.queue = function(name, args) {
  *       // Runs when you call `doc.deleteOne()`
  *     });
  *
- * @param {String|RegExp} The method name or regular expression to match method name
+ * @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.
@@ -1633,7 +1650,7 @@ Schema.prototype.pre = function(name) {
  *       console.log('this fires after the post find hook');
  *     });
  *
- * @param {String|RegExp} The method name or regular expression to match method name
+ * @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.
@@ -1673,8 +1690,14 @@ Schema.prototype.post = function(name) {
  *     s.plugin(schema => console.log(schema.path('name').path));
  *     mongoose.model('Test', s); // Prints 'name'
  *
- * @param {Function} plugin callback
- * @param {Object} [opts]
+ * Or with Options:
+ *
+ *     const s = new Schema({ name: String });
+ *     s.plugin((schema, opts) => console.log(opts.text, schema.path('name').path), { text: "Schema Path 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
  * @see plugins
  * @api public
  */
@@ -1701,7 +1724,7 @@ Schema.prototype.plugin = function(fn, opts) {
 /**
  * Adds an instance method to documents constructed from Models compiled from this schema.
  *
- * #### Example
+ * #### Example:
  *
  *     const schema = kittySchema = new Schema(..);
  *
@@ -1722,13 +1745,14 @@ Schema.prototype.plugin = function(fn, opts) {
  *     });
  *
  *     // later
+ *     const fizz = new Kitty;
  *     fizz.purr();
  *     fizz.scratch();
  *
  * 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](/docs/guide.html#methods)
  *
- * @param {String|Object} method name
- * @param {Function} [fn]
+ * @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
  */
 
@@ -1748,7 +1772,7 @@ Schema.prototype.method = function(name, fn, options) {
 /**
  * Adds static "class" methods to Models compiled from this schema.
  *
- * #### Example
+ * #### Example:
  *
  *     const schema = new Schema(..);
  *     // Equivalent to `schema.statics.findByName = function(name) {}`;
@@ -1759,10 +1783,21 @@ Schema.prototype.method = function(name, fn, options) {
  *     const Drink = mongoose.model('Drink', schema);
  *     await Drink.findByName('LaCroix');
  *
+ * If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as methods.
+ *
+ *     schema.static({
+ *         findByName: function () {..}
+ *       , findByCost: function () {..}
+ *     });
+ *
+ *     const Drink = mongoose.model('Drink', schema);
+ *     await Drink.findByName('LaCroix');
+ *     await Drink.findByCost(3);
+ *
  * 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
- * @param {Function} [fn]
+ * @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 /docs/guide.html#statics
  */
@@ -1781,11 +1816,11 @@ Schema.prototype.static = function(name, fn) {
 /**
  * Defines an index (most likely compound) for this schema.
  *
- * #### Example
+ * #### Example:
  *
  *     schema.index({ first: 1, last: -1 })
  *
- * @param {Object} fields
+ * @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/2.0/api/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.
  * @api public
@@ -1806,14 +1841,14 @@ Schema.prototype.index = function(fields, options) {
 /**
  * Sets a schema option.
  *
- * #### Example
+ * #### Example:
  *
  *     schema.set('strict'); // 'true' by default
  *     schema.set('strict', false); // Sets 'strict' to false
  *     schema.set('strict'); // 'false'
  *
- * @param {String} key option name
- * @param {Object} [value] if not passed, the current option value is returned
+ * @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
  * @see Schema ./
  * @api public
  */
@@ -1861,7 +1896,7 @@ Schema.prototype.set = function(key, value, _tags) {
  *     schema.set('strict', false);
  *     schema.get('strict'); // false
  *
- * @param {String} key option name
+ * @param {String} key The name of the Option to get the current value for
  * @api public
  * @return {Any} the option's value
  */
@@ -1870,16 +1905,17 @@ Schema.prototype.get = function(key) {
   return this.options[key];
 };
 
+const indexTypes = '2d 2dsphere hashed text'.split(' ');
+
 /**
  * The allowed index types
  *
- * @receiver Schema
- * @static indexTypes
+ * @property {String[]} indexTypes
+ * @memberOf Schema
+ * @static
  * @api public
  */
 
-const indexTypes = '2d 2dsphere hashed text'.split(' ');
-
 Object.defineProperty(Schema, 'indexTypes', {
   get: function() {
     return indexTypes;
@@ -1926,7 +1962,7 @@ Schema.prototype.indexes = function() {
 /**
  * Creates a virtual type with the given name.
  *
- * @param {String} 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](/docs/populate.html#populate-virtuals).
  * @param {String|Function} [options.localField] Required for populate virtuals. See [populate virtual docs](/docs/populate.html#populate-virtuals) for more information.
@@ -2044,8 +2080,8 @@ Schema.prototype.virtual = function(name, options) {
 /**
  * Returns the virtual type with the given `name`.
  *
- * @param {String} name
- * @return {VirtualType}
+ * @param {String} name The name of the Virtual to get
+ * @return {VirtualType|null}
  */
 
 Schema.prototype.virtualpath = function(name) {
@@ -2062,7 +2098,13 @@ Schema.prototype.virtualpath = function(name) {
  *     schema.path('name'); // Undefined
  *     schema.path('age'); // SchemaNumber { ... }
  *
- * @param {String|Array} path
+ * Or as a Array:
+ *
+ *     schema.remove(['name', 'age']);
+ *     schema.path('name'); // Undefined
+ *     schema.path('age'); // Undefined
+ *
+ * @param {String|Array} path The Path(s) to remove
  * @return {Schema} the Schema instance
  * @api public
  */
@@ -2150,7 +2192,7 @@ function _deletePath(schema, name) {
  * userSchema.loadClass(UserClass);
  * ```
  *
- * @param {Function} model
+ * @param {Function} model The Class to load
  * @param {Boolean} [virtualsOnly] if truthy, only pulls virtuals from the class, not methods or statics
  */
 Schema.prototype.loadClass = function(model, virtualsOnly) {

package/lib/schematype.js

@@ -206,7 +206,7 @@ SchemaType.prototype.splitPath = function() {
  * @param {Function|false} caster Function that casts arbitrary values to this type, or throws an error if casting failed
  * @return {Function}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function cast
  * @api public
  */
@@ -239,9 +239,7 @@ SchemaType.cast = function cast(caster) {
  *
  * @param {Function|false} caster Function that casts arbitrary values to this type, or throws an error if casting failed
  * @return {Function}
- * @static
- * @receiver SchemaType
- * @function cast
+ * @memberOf SchemaType
  * @api public
  */
 
@@ -279,10 +277,10 @@ SchemaType.prototype.cast = function cast() {
  *     mongoose.SchemaTypes.String.set('trim', true);
  *
  * @param {String} option The name of the option you'd like to set (e.g. trim, lowercase, etc...)
- * @param {*} value The value of the option you'd like to set.
+ * @param {Any} value The value of the option you'd like to set.
  * @return {void}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function set
  * @api public
  */
@@ -305,7 +303,7 @@ SchemaType.set = function set(option, value) {
  * @param {Function} getter
  * @return {this}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function get
  * @api public
  */
@@ -1244,7 +1242,7 @@ SchemaType.prototype.select = function select(val) {
  * @param {any} value
  * @param {Function} callback
  * @param {Object} scope
- * @api private
+ * @api public
  */
 
 SchemaType.prototype.doValidate = function(value, fn, scope, options) {
@@ -1636,7 +1634,7 @@ SchemaType.prototype._castForQuery = function(val) {
  * @param {Function} fn
  * @return {Function}
  * @static
- * @receiver SchemaType
+ * @memberOf SchemaType
  * @function checkRequired
  * @api public
  */

package/lib/types/DocumentArray/methods/index.js

@@ -35,7 +35,7 @@ const methods = {
    *
    * @method _cast
    * @api private
-   * @receiver MongooseDocumentArray
+   * @memberOf MongooseDocumentArray
    */
 
   _cast(value, index) {

package/lib/types/buffer.js

@@ -70,7 +70,8 @@ MongooseBuffer.mixin = {
    *
    * @api private
    * @property _subtype
-   * @memberOf MongooseBuffer
+   * @memberOf MongooseBuffer.mixin
+   * @static
    */
 
   _subtype: undefined,
@@ -80,7 +81,8 @@ MongooseBuffer.mixin = {
    *
    * @api private
    * @method _markModified
-   * @memberOf MongooseBuffer
+   * @memberOf MongooseBuffer.mixin
+   * @static
    */
 
   _markModified: function() {
@@ -97,7 +99,8 @@ MongooseBuffer.mixin = {
    *
    * @api public
    * @method write
-   * @memberOf MongooseBuffer
+   * @memberOf MongooseBuffer.mixin
+   * @static
    */
 
   write: function() {
@@ -120,7 +123,8 @@ MongooseBuffer.mixin = {
    * @return {Number} The number of bytes copied.
    * @param {Buffer} target
    * @method copy
-   * @memberOf MongooseBuffer
+   * @memberOf MongooseBuffer.mixin
+   * @static
    */
 
   copy: function(target) {

package/lib/types/decimal128.js

@@ -1,7 +1,7 @@
 /**
  * Decimal128 type constructor
  *
- * #### Example
+ * #### Example:
  *
  *     const id = new mongoose.Types.Decimal128('3.1415');
  *

package/lib/types/map.js

@@ -275,7 +275,7 @@ Object.defineProperty(MongooseMap.prototype, '$__schemaType', {
  *
  * @api public
  * @property $isMongooseMap
- * @memberOf Map
+ * @memberOf MongooseMap
  * @instance
  */
 

package/lib/types/objectid.js

@@ -1,7 +1,7 @@
 /**
  * ObjectId type constructor
  *
- * #### Example
+ * #### Example:
  *
  *     const id = new mongoose.Types.ObjectId;
  *

package/lib/types/subdocument.js

@@ -188,7 +188,7 @@ Subdocument.prototype.isModified = function(paths, modifiedPaths) {
  * @param {String} path the field to mark as valid
  * @api private
  * @method $markValid
- * @receiver Subdocument
+ * @memberOf Subdocument
  */
 
 Subdocument.prototype.$markValid = function(path) {

package/lib/virtualtype.js

@@ -75,7 +75,7 @@ VirtualType.prototype.clone = function() {
  * Mongoose calls the getter function with the below 3 parameters.
  *
  * - `value`: the value returned by the previous getter. If there is only one getter, `value` will be `undefined`.
- * - `virtual`: the virtual object you called `.get()` on
+ * - `virtual`: the virtual object you called `.get()` on.
  * - `doc`: the document this virtual is attached to. Equivalent to `this`.
  *
  * #### Example:
@@ -85,7 +85,7 @@ VirtualType.prototype.clone = function() {
  *       return this.name.first + ' ' + this.name.last;
  *     });
  *
- * @param {Function(Any, VirtualType, Document)} fn
+ * @param {function} fn
  * @return {VirtualType} this
  * @api public
  */
@@ -100,8 +100,8 @@ VirtualType.prototype.get = function(fn) {
  *
  * Mongoose calls the setter function with the below 3 parameters.
  *
- * - `value`: the value being set
- * - `virtual`: the virtual object you're calling `.set()` on
+ * - `value`: the value being set.
+ * - `virtual`: the virtual object you're calling `.set()` on.
  * - `doc`: the document this virtual is attached to. Equivalent to `this`.
  *
  * #### Example:
@@ -120,7 +120,7 @@ VirtualType.prototype.get = function(fn) {
  *     doc.name.first; // 'Jean-Luc'
  *     doc.name.last; // 'Picard'
  *
- * @param {Function(Any, VirtualType, Document)} fn
+ * @param {function} fn
  * @return {VirtualType} this
  * @api public
  */