mongoose 6.2.7 → 6.2.10

package/lib/schema.js

@@ -38,7 +38,7 @@ let id = 0;
 /**
  * Schema constructor.
  *
- * ####Example:
+ * #### Example:
  *
  *     const child = new Schema({ name: String });
  *     const schema = new Schema({ name: String, age: Number, children: [child] });
@@ -47,7 +47,7 @@ let id = 0;
  *     // setting schema options
  *     new Schema({ name: String }, { _id: false, autoIndex: false })
  *
- * ####Options:
+ * #### Options:
  *
  * - [autoIndex](/docs/guide.html#autoIndex): bool - defaults to null (which means use the connection's autoIndex option)
  * - [autoCreate](/docs/guide.html#autoCreate): bool - defaults to null (which means use the connection's autoCreate option)
@@ -77,10 +77,10 @@ let id = 0;
  * - [timestamps](/docs/guide.html#timestamps): object or boolean - defaults to `false`. If true, Mongoose adds `createdAt` and `updatedAt` properties to your schema and manages those properties for you.
  * - [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:
+ * #### Options for Nested Schemas:
  * - `excludeIndexes`: bool - defaults to `false`. If `true`, skip building indexes on this schema's paths.
  *
- * ####Note:
+ * #### Note:
  *
  * _When nesting schemas, (`children` in the example above), always declare the child schema first before passing it into its parent._
  *
@@ -231,7 +231,7 @@ Object.defineProperty(Schema.prototype, 'childSchemas', {
  * This property is typically only useful for plugin authors and advanced users.
  * You do not need to interact with this property at all to use mongoose.
  *
- * ####Example:
+ * #### Example:
  *     const schema = new Schema({});
  *     schema.virtual('answer').get(() => 42);
  *
@@ -253,7 +253,7 @@ Object.defineProperty(Schema.prototype, 'virtuals', {
 /**
  * The original object passed to the schema constructor
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ a: String }).add({ b: String });
  *     schema.obj; // { a: String }
@@ -270,7 +270,7 @@ Schema.prototype.obj;
  * The paths defined on this schema. The keys are the top-level paths
  * in this schema, and the values are instances of the SchemaType class.
  *
- * ####Example:
+ * #### Example:
  *     const schema = new Schema({ name: String }, { _id: false });
  *     schema.paths; // { name: SchemaString { ... } }
  *
@@ -288,7 +288,7 @@ Schema.prototype.paths;
 /**
  * Schema as a tree
  *
- * ####Example:
+ * #### Example:
  *     {
  *         '_id'     : ObjectId
  *       , 'nested'  : {
@@ -307,7 +307,7 @@ Schema.prototype.tree;
 /**
  * Returns a deep copy of the schema
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ name: String });
  *     const clone = schema.clone();
@@ -381,7 +381,7 @@ Schema.prototype._clone = function _clone(Constructor) {
  *
  * This method is analagous to [Lodash's `pick()` function](https://lodash.com/docs/4.17.15#pick) for Mongoose schemas.
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = Schema({ name: String, age: Number });
  *     // Creates a new schema with the same `name` path as `schema`,
@@ -472,7 +472,7 @@ Schema.prototype.defaultOptions = function(options) {
 /**
  * Adds key path / schema type pairs to this schema.
  *
- * ####Example:
+ * #### Example:
  *
  *     const ToySchema = new Schema();
  *     ToySchema.add({ name: 'string', color: 'string', price: 'number' });
@@ -646,7 +646,7 @@ 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
@@ -1133,7 +1133,7 @@ function createMapNestedSchemaType(schema, schemaType, path, obj, options) {
  *
  * The callback is passed the pathname and the schemaType instance.
  *
- * ####Example:
+ * #### Example:
  *
  *     const userSchema = new Schema({ name: String, registeredAt: Date });
  *     userSchema.eachPath((pathname, schematype) => {
@@ -1162,7 +1162,7 @@ Schema.prototype.eachPath = function(fn) {
 /**
  * Returns an Array of path strings that are required by this schema.
  *
- * ####Example:
+ * #### Example:
  *     const s = new Schema({
  *       name: { type: String, required: true },
  *       age: { type: String, required: true },
@@ -1214,7 +1214,7 @@ Schema.prototype.indexedPaths = function indexedPaths() {
  *
  * Given a path, returns whether it is a real, virtual, nested, or ad-hoc/undefined path.
  *
- * ####Example:
+ * #### Example:
  *     const s = new Schema({ name: String, nested: { foo: String } });
  *     s.virtual('foo').get(() => 42);
  *     s.pathType('name'); // "real"
@@ -1371,7 +1371,7 @@ function getPositionalPath(self, path) {
 /**
  * Adds a method call to the queue.
  *
- * ####Example:
+ * #### Example:
  *
  *     schema.methods.print = function() { console.log(this); };
  *     schema.queue('print', []); // Print the doc every one is instantiated
@@ -1392,7 +1392,7 @@ Schema.prototype.queue = function(name, args) {
 /**
  * Defines a pre hook for the model.
  *
- * ####Example
+ * #### Example
  *
  *     const toySchema = new Schema({ name: String, created: Date });
  *
@@ -1514,7 +1514,7 @@ Schema.prototype.post = function(name) {
 /**
  * Registers a plugin for this schema.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = new Schema({ name: String });
  *     s.plugin(schema => console.log(schema.path('name').path));
@@ -1548,7 +1548,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(..);
  *
@@ -1595,7 +1595,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) {}`;
@@ -1628,7 +1628,7 @@ Schema.prototype.static = function(name, fn) {
 /**
  * Defines an index (most likely compound) for this schema.
  *
- * ####Example
+ * #### Example
  *
  *     schema.index({ first: 1, last: -1 })
  *
@@ -1653,7 +1653,7 @@ 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
@@ -1702,7 +1702,7 @@ Schema.prototype.set = function(key, value, _tags) {
 /**
  * Gets a schema option.
  *
- * ####Example:
+ * #### Example:
  *
  *     schema.get('strict'); // true
  *     schema.set('strict', false);
@@ -1740,7 +1740,7 @@ Object.defineProperty(Schema, 'indexTypes', {
  * Returns a list of indexes that this schema declares, via `schema.index()` or by `index: true` in a path's options.
  * Indexes are expressed as an array `[spec, options]`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const userSchema = new Schema({
  *       email: { type: String, required: true, unique: true },
@@ -1902,7 +1902,7 @@ Schema.prototype.virtualpath = function(name) {
 /**
  * Removes the given `path` (or [`paths`]).
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ name: String, age: Number });
  *     schema.remove('name');
@@ -1969,7 +1969,7 @@ function _deletePath(schema, name) {
  * [statics](/docs/guide.html#statics), and
  * [methods](/docs/guide.html#methods).
  *
- * ####Example:
+ * #### Example:
  *
  * ```javascript
  * const md5 = require('md5');
@@ -2232,12 +2232,12 @@ module.exports = exports = Schema;
 /**
  * The various built-in Mongoose Schema Types.
  *
- * ####Example:
+ * #### Example:
  *
  *     const mongoose = require('mongoose');
  *     const ObjectId = mongoose.Schema.Types.ObjectId;
  *
- * ####Types:
+ * #### Types:
  *
  * - [String](/docs/schematypes.html#strings)
  * - [Number](/docs/schematypes.html#numbers)

package/lib/schematype.js

@@ -22,11 +22,13 @@ const populateModelSymbol = require('./helpers/symbols').populateModelSymbol;
 const CastError = MongooseError.CastError;
 const ValidatorError = MongooseError.ValidatorError;
 
+const setOptionsForDefaults = { _skipMarkModified: true };
+
 /**
  * SchemaType constructor. Do **not** instantiate `SchemaType` directly.
  * Mongoose converts your schema paths into SchemaTypes automatically.
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ name: String });
  *     schema.path('name') instanceof SchemaType; // true
@@ -131,7 +133,7 @@ SchemaType.prototype.OptionsConstructor = SchemaTypeOptions;
 /**
  * The path to this SchemaType in a Schema.
  *
- * ####Example:
+ * #### Example:
  *     const schema = new Schema({ name: String });
  *     schema.path('name').path; // 'name'
  *
@@ -145,7 +147,7 @@ SchemaType.prototype.path;
 /**
  * The validators that Mongoose should run to validate properties at this SchemaType's path.
  *
- * ####Example:
+ * #### Example:
  *     const schema = new Schema({ name: { type: String, required: true } });
  *     schema.path('name').validators.length; // 1, the `required` validator
  *
@@ -159,7 +161,7 @@ SchemaType.prototype.validators;
 /**
  * True if this SchemaType has a required validator. False otherwise.
  *
- * ####Example:
+ * #### Example:
  *     const schema = new Schema({ name: { type: String, required: true } });
  *     schema.path('name').isRequired; // true
  *
@@ -192,7 +194,7 @@ SchemaType.prototype.splitPath = function() {
 /**
  * Get/set the function used to cast arbitrary values to this type.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Disallow `null` for numbers, and don't try to cast any values to
  *     // numbers, so even strings like '123' will cause a CastError.
@@ -225,7 +227,7 @@ SchemaType.cast = function cast(caster) {
  * Get/set the function used to cast arbitrary values to this particular schematype instance.
  * Overrides `SchemaType.cast()`.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Disallow `null` for numbers, and don't try to cast any values to
  *     // numbers, so even strings like '123' will cause a CastError.
@@ -271,7 +273,7 @@ SchemaType.prototype.cast = function cast() {
 /**
  * Sets a default option for this schema type.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Make all strings be trimmed by default
  *     mongoose.SchemaTypes.String.set('trim', true);
@@ -295,7 +297,7 @@ SchemaType.set = function set(option, value) {
 /**
  * Attaches a getter for all instances of this schema type.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Make all numbers round down
  *     mongoose.Number.get(function(v) { return Math.floor(v); });
@@ -316,7 +318,7 @@ SchemaType.get = function(getter) {
 /**
  * Sets a default value for this SchemaType.
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ n: { type: Number, default: 10 })
  *     const M = db.model('M', schema)
@@ -325,7 +327,7 @@ SchemaType.get = function(getter) {
  *
  * Defaults can be either `functions` which return the value to use as the default or the literal value itself. Either way, the value will be cast based on its schema type before being set during document creation.
  *
- * ####Example:
+ * #### Example:
  *
  *     // values are cast:
  *     const schema = new Schema({ aNumber: { type: Number, default: 4.815162342 }})
@@ -379,7 +381,7 @@ SchemaType.prototype.default = function(val) {
 /**
  * Declares the index options for this schematype.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = new Schema({ name: { type: String, index: true })
  *     const s = new Schema({ loc: { type: [Number], index: 'hashed' })
@@ -390,7 +392,7 @@ SchemaType.prototype.default = function(val) {
  *     s.path('my.date').index({ expires: 60 });
  *     s.path('my.path').index({ unique: true, sparse: true });
  *
- * ####NOTE:
+ * #### Note:
  *
  * _Indexes are created [in the background](https://docs.mongodb.com/manual/core/index-creation/#index-creation-background)
  * by default. If `background` is set to `false`, MongoDB will not execute any
@@ -411,7 +413,7 @@ SchemaType.prototype.index = function(options) {
 /**
  * Declares an unique index.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = new Schema({ name: { type: String, unique: true }});
  *     s.path('name').index({ unique: true });
@@ -449,7 +451,7 @@ SchemaType.prototype.unique = function(bool) {
 /**
  * Declares a full text index.
  *
- * ###Example:
+ * ### Example:
  *
  *      const s = new Schema({name : {type: String, text : true })
  *      s.path('name').index({text : true});
@@ -485,7 +487,7 @@ SchemaType.prototype.text = function(bool) {
 /**
  * Declares a sparse index.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = new Schema({ name: { type: String, sparse: true } });
  *     s.path('name').index({ sparse: true });
@@ -522,7 +524,7 @@ SchemaType.prototype.sparse = function(bool) {
  * Defines this path as immutable. Mongoose prevents you from changing
  * immutable paths unless the parent document has [`isNew: true`](/docs/api.html#document_Document-isNew).
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({
  *       name: { type: String, immutable: true },
@@ -540,7 +542,7 @@ SchemaType.prototype.sparse = function(bool) {
  * Mongoose also prevents changing immutable properties using `updateOne()`
  * and `updateMany()` based on [strict mode](/docs/guide.html#strict).
  *
- * ####Example:
+ * #### Example:
  *
  *     // Mongoose will strip out the `name` update, because `name` is immutable
  *     Model.updateOne({}, { $set: { name: 'test2' }, $inc: { age: 1 } });
@@ -574,7 +576,7 @@ SchemaType.prototype.immutable = function(bool) {
  * Mongoose calls this function with one parameter: the current `value` of the path. Mongoose
  * then uses the return value in the JSON output.
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({
  *       date: { type: Date, transform: v => v.getFullYear() }
@@ -603,19 +605,21 @@ SchemaType.prototype.transform = function(fn) {
 /**
  * Adds a setter to this schematype.
  *
- * ####Example:
+ * #### Example:
  *
- *     function capitalize (val) {
- *       if (typeof val !== 'string') val = '';
- *       return val.charAt(0).toUpperCase() + val.substring(1);
- *     }
+ * ```javascript
+ * function capitalize (val) {
+ *   if (typeof val !== 'string') val = '';
+ *   return val.charAt(0).toUpperCase() + val.substring(1);
+ * }
  *
- *     // defining within the schema
- *     const s = new Schema({ name: { type: String, set: capitalize }});
+ * // defining within the schema
+ * const s = new Schema({ name: { type: String, set: capitalize }});
  *
- *     // or with the SchemaType
- *     const s = new Schema({ name: String })
- *     s.path('name').set(capitalize);
+ * // or with the SchemaType
+ * const s = new Schema({ name: String })
+ * s.path('name').set(capitalize);
+ * ```
  *
  * Setters allow you to transform the data before it gets to the raw mongodb
  * document or query.
@@ -627,52 +631,58 @@ SchemaType.prototype.transform = function(fn) {
  *
  * You can set up email lower case normalization easily via a Mongoose setter.
  *
- *     function toLower(v) {
- *       return v.toLowerCase();
- *     }
+ * ```javascript
+ * function toLower(v) {
+ *   return v.toLowerCase();
+ * }
  *
- *     const UserSchema = new Schema({
- *       email: { type: String, set: toLower }
- *     });
+ * const UserSchema = new Schema({
+ *   email: { type: String, set: toLower }
+ * });
  *
- *     const User = db.model('User', UserSchema);
+ * const User = db.model('User', UserSchema);
  *
- *     const user = new User({email: 'AVENUE@Q.COM'});
- *     console.log(user.email); // 'avenue@q.com'
+ * const user = new User({email: 'AVENUE@Q.COM'});
+ * console.log(user.email); // 'avenue@q.com'
  *
- *     // or
- *     const user = new User();
- *     user.email = 'Avenue@Q.com';
- *     console.log(user.email); // 'avenue@q.com'
- *     User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }); // update to 'avenue@q.com'
+ * // or
+ * const user = new User();
+ * user.email = 'Avenue@Q.com';
+ * console.log(user.email); // 'avenue@q.com'
+ * User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }); // update to 'avenue@q.com'
+ * ```
  *
  * As you can see above, setters allow you to transform the data before it
  * stored in MongoDB, or before executing a query.
  *
  * _NOTE: we could have also just used the built-in `lowercase: true` SchemaType option instead of defining our own function._
  *
- *     new Schema({ email: { type: String, lowercase: true }})
+ * ```javascript
+ * new Schema({ email: { type: String, lowercase: true }})
+ * ```
  *
  * Setters are also passed a second argument, the schematype on which the setter was defined. This allows for tailored behavior based on options passed in the schema.
  *
- *     function inspector (val, priorValue, schematype) {
- *       if (schematype.options.required) {
- *         return schematype.path + ' is required';
- *       } else {
- *         return val;
- *       }
- *     }
+ * ```javascript
+ * function inspector (val, priorValue, schematype) {
+ *   if (schematype.options.required) {
+ *     return schematype.path + ' is required';
+ *   } else {
+ *     return val;
+ *   }
+ * }
  *
- *     const VirusSchema = new Schema({
- *       name: { type: String, required: true, set: inspector },
- *       taxonomy: { type: String, set: inspector }
- *     })
+ * const VirusSchema = new Schema({
+ *   name: { type: String, required: true, set: inspector },
+ *   taxonomy: { type: String, set: inspector }
+ * })
  *
- *     const Virus = db.model('Virus', VirusSchema);
- *     const v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });
+ * const Virus = db.model('Virus', VirusSchema);
+ * const v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });
  *
- *     console.log(v.name);     // name is required
- *     console.log(v.taxonomy); // Parvovirinae
+ * console.log(v.name);     // name is required
+ * console.log(v.taxonomy); // Parvovirinae
+ * ```
  *
  * You can also use setters to modify other properties on the document. If
  * you're setting a property `name` on a document, the setter will run with
@@ -708,7 +718,7 @@ SchemaType.prototype.set = function(fn) {
 /**
  * Adds a getter to this schematype.
  *
- * ####Example:
+ * #### Example:
  *
  *     function dob (val) {
  *       if (!val) return val;
@@ -784,7 +794,7 @@ SchemaType.prototype.get = function(fn) {
  *
  * The error message argument is optional. If not passed, the [default generic error message template](#error_messages_MongooseError-messages) will be used.
  *
- * ####Examples:
+ * #### Examples:
  *
  *     // make sure every value is equal to "something"
  *     function validator (val) {
@@ -810,7 +820,7 @@ SchemaType.prototype.get = function(fn) {
  *     const schema = new Schema({ name: 'string' });
  *     schema.path('name').validate(validator, 'validation of `{PATH}` failed with value `{VALUE}`');
  *
- * ####Error message templates:
+ * #### Error message templates:
  *
  * From the examples above, you may have noticed that error messages support
  * basic templating. There are a few other template keywords besides `{PATH}`
@@ -837,7 +847,7 @@ SchemaType.prototype.get = function(fn) {
  *       message: function(props) { return props.reason.message; }
  *     });
  *
- * ####Asynchronous validation:
+ * #### Asynchronous validation:
  *
  * Mongoose supports validators that return a promise. A validator that returns
  * a promise is called an _async validator_. Async validators run in
@@ -930,7 +940,7 @@ SchemaType.prototype.validate = function(obj, message, type) {
  * Adds a required validator to this SchemaType. The validator gets added
  * to the front of this SchemaType's validators array using `unshift()`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const s = new Schema({ born: { type: Date, required: true })
  *
@@ -1069,7 +1079,7 @@ SchemaType.prototype.required = function(required, message) {
  * Set the model that this path refers to. This is the option that [populate](https://mongoosejs.com/docs/populate.html)
  * looks at to determine the foreign collection it should query.
  *
- * ####Example:
+ * #### Example:
  *     const userSchema = new Schema({ name: String });
  *     const User = mongoose.model('User', userSchema);
  *
@@ -1124,7 +1134,7 @@ SchemaType.prototype.getDefault = function(scope, init) {
       ret = utils.clone(ret);
     }
 
-    const casted = this.applySetters(ret, scope, init);
+    const casted = this.applySetters(ret, scope, init, undefined, setOptionsForDefaults);
     if (casted && !Array.isArray(casted) && casted.$isSingleNested) {
       casted.$__parent = scope;
     }
@@ -1211,7 +1221,7 @@ SchemaType.prototype.applyGetters = function(value, scope) {
  *
  * Set to `true` if this path should always be included in the results, `false` if it should be excluded by default. This setting can be overridden at the query level.
  *
- * ####Example:
+ * #### Example:
  *
  *     T = db.model('T', new Schema({ x: { type: String, select: true }}));
  *     T.find(..); // field x will always be selected ..
@@ -1340,7 +1350,7 @@ function _validate(ok, validatorProperties) {
 /**
  * Performs a validation of `value` using the validators declared for this SchemaType.
  *
- * ####Note:
+ * #### Note:
  *
  * This method ignores the asynchronous validators.
  *
@@ -1618,7 +1628,7 @@ SchemaType.prototype._castForQuery = function(val) {
  * Override the function the required validator uses to check whether a value
  * passes the `required` check. Override this on the individual SchemaType.
  *
- * ####Example:
+ * #### Example:
  *
  *     // Use this to allow empty strings to pass the `required` validator
  *     mongoose.Schema.Types.String.checkRequired(v => typeof v === 'string');

package/lib/types/ArraySubdocument.js

@@ -154,7 +154,7 @@ ArraySubdocument.prototype.$parent = function() {
 /**
  * Returns this subdocument's parent array.
  *
- * ####Example:
+ * #### Example:
  *
  *     const Test = mongoose.model('Test', new Schema({
  *       docArr: [{ name: String }]

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

@@ -89,7 +89,7 @@ const methods = {
   /**
    * Searches array items for the first document with a matching _id.
    *
-   * ####Example:
+   * #### Example:
    *
    *     const embeddedDoc = m.array.id(some_id);
    *
@@ -141,7 +141,7 @@ const methods = {
   /**
    * Returns a native js Array of plain js objects
    *
-   * ####NOTE:
+   * #### Note:
    *
    * _Each sub-document is converted to a plain object by calling its `#toObject` method._
    *

package/lib/types/array/index.js

@@ -16,7 +16,7 @@ const arraySchemaSymbol = require('../../helpers/symbols').arraySchemaSymbol;
 /**
  * Mongoose Array constructor.
  *
- * ####NOTE:
+ * #### Note:
  *
  * _Values always have to be passed to the constructor to initialize, otherwise `MongooseArray#push` will mark the array as modified._
  *