mongoose 6.2.9 → 6.3.0

package/lib/schematype.js

@@ -28,7 +28,7 @@ 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
@@ -133,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'
  *
@@ -147,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
  *
@@ -161,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
  *
@@ -194,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.
@@ -227,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.
@@ -273,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);
@@ -297,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); });
@@ -318,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)
@@ -327,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 }})
@@ -381,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' })
@@ -392,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
@@ -413,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 });
@@ -451,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});
@@ -487,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 });
@@ -524,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 },
@@ -542,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 } });
@@ -576,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() }
@@ -605,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.
@@ -629,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
@@ -710,7 +718,7 @@ SchemaType.prototype.set = function(fn) {
 /**
  * Adds a getter to this schematype.
  *
- * ####Example:
+ * #### Example:
  *
  *     function dob (val) {
  *       if (!val) return val;
@@ -786,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) {
@@ -812,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}`
@@ -839,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
@@ -932,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 })
  *
@@ -1071,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);
  *
@@ -1120,7 +1128,6 @@ SchemaType.prototype.getDefault = function(scope, init) {
     ret = this.defaultValue;
   }
 
-
   if (ret !== null && ret !== undefined) {
     if (typeof ret === 'object' && (!this.options || !this.options.shared)) {
       ret = utils.clone(ret);
@@ -1213,7 +1220,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 ..
@@ -1342,7 +1349,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.
  *
@@ -1620,7 +1627,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._
  *

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

@@ -100,7 +100,7 @@ const methods = {
   /**
    * Atomically shifts the array at most one time per document `save()`.
    *
-   * ####NOTE:
+   * #### Note:
    *
    * _Calling this multiple times on an array before saving sends the same command as calling it once._
    * _This update is implemented using the MongoDB [$pop](https://www.mongodb.org/display/DOCS/Updating/#Updating-%24pop) method which enforces this restriction._
@@ -149,7 +149,7 @@ const methods = {
    *
    * #### NOTE:
    *
-   * _Calling this mulitple times on an array before saving sends the same command as calling it once._
+   * _Calling this multiple times on an array before saving sends the same command as calling it once._
    * _This update is implemented using the MongoDB [$pop](https://www.mongodb.org/display/DOCS/Updating/#Updating-%24pop) method which enforces this restriction._
    *
    *      doc.array = [1,2,3];
@@ -365,7 +365,7 @@ const methods = {
   /**
    * Adds values to the array if not already present.
    *
-   * ####Example:
+   * #### Example:
    *
    *     console.log(doc.array) // [2,3,4]
    *     const added = doc.array.addToSet(4,5);
@@ -498,7 +498,7 @@ const methods = {
   /**
    * Pushes items to the array non-atomically.
    *
-   * ####NOTE:
+   * #### Note:
    *
    * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
    *
@@ -519,7 +519,7 @@ const methods = {
   /**
    * Wraps [`Array#pop`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/pop) with proper change tracking.
    *
-   * ####Note:
+   * #### Note:
    *
    * _marks the entire array as modified which will pass the entire thing to $set potentially overwriting any changes that happen between when you retrieved the object and when you save it._
    *
@@ -541,7 +541,7 @@ const methods = {
    * the provided value to an embedded document and comparing using
    * [the `Document.equals()` function.](/docs/api.html#document_Document-equals)
    *
-   * ####Examples:
+   * #### Examples:
    *
    *     doc.array.pull(ObjectId)
    *     doc.array.pull({ _id: 'someId' })
@@ -611,7 +611,7 @@ const methods = {
   /**
    * Wraps [`Array#push`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/push) with proper change tracking.
    *
-   * ####Example:
+   * #### Example:
    *
    *     const schema = Schema({ nums: [Number] });
    *     const Model = mongoose.model('Test', schema);
@@ -706,7 +706,7 @@ const methods = {
   /**
    * Sets the casted `val` at index `i` and marks the array modified.
    *
-   * ####Example:
+   * #### Example:
    *
    *     // given documents based on the following
    *     const Doc = mongoose.model('Doc', new Schema({ array: [Number] }));
@@ -745,14 +745,14 @@ const methods = {
   /**
    * Wraps [`Array#shift`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/unshift) with proper change tracking.
    *
-   * ####Example:
+   * #### Example:
    *
    *     doc.array = [2,3];
    *     const res = doc.array.shift();
    *     console.log(res) // 2
    *     console.log(doc.array) // [3]
    *
-   * ####Note:
+   * #### Note:
    *
    * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
    *
@@ -772,7 +772,7 @@ const methods = {
   /**
    * Wraps [`Array#sort`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort) with proper change tracking.
    *
-   * ####NOTE:
+   * #### Note:
    *
    * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
    *
@@ -792,7 +792,7 @@ const methods = {
   /**
    * Wraps [`Array#splice`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/splice) with proper change tracking and casting.
    *
-   * ####Note:
+   * #### Note:
    *
    * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it._
    *
@@ -869,7 +869,7 @@ const methods = {
   /**
    * Wraps [`Array#unshift`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/unshift) with proper change tracking.
    *
-   * ####Note:
+   * #### Note:
    *
    * _marks the entire array as modified, which if saved, will store it as a `$set` operation, potentially overwriting any changes that happen between when you retrieved the object and when you save it._
    *

package/lib/types/buffer.js

@@ -113,7 +113,7 @@ MongooseBuffer.mixin = {
   /**
    * Copies the buffer.
    *
-   * ####Note:
+   * #### Note:
    *
    * `Buffer#copy` does not mark `target` as modified so you must copy from a `MongooseBuffer` for it to work as expected. This is a work around since `copy` modifies the target, not this.
    *

package/lib/types/decimal128.js

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

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

@@ -58,7 +58,7 @@ Subdocument.prototype.toBSON = function() {
 /**
  * Used as a stub for middleware
  *
- * ####NOTE:
+ * #### Note:
  *
  * _This is a no-op. Does not actually save the doc to the db._
  *
@@ -116,7 +116,7 @@ Subdocument.prototype.$__pathRelativeToParent = function(p) {
 /**
  * Used as a stub for middleware
  *
- * ####NOTE:
+ * #### Note:
  *
  * _This is a no-op. Does not actually save the doc to the db._
  *
@@ -269,6 +269,35 @@ Subdocument.prototype.ownerDocument = function() {
   return this.$__.ownerDocument;
 };
 
+/*!
+ * ignore
+ */
+
+Subdocument.prototype.$__fullPathWithIndexes = function() {
+  let parent = this; // eslint-disable-line consistent-this
+  const paths = [];
+  const seenDocs = new Set([parent]);
+
+  while (true) {
+    if (typeof parent.$__pathRelativeToParent !== 'function') {
+      break;
+    }
+    paths.unshift(parent.$__pathRelativeToParent(void 0, false));
+    const _parent = parent.$parent();
+    if (_parent == null) {
+      break;
+    }
+    parent = _parent;
+    if (seenDocs.has(parent)) {
+      throw new Error('Infinite subdocument loop: subdoc with _id ' + parent._id + ' is a parent of itself');
+    }
+
+    seenDocs.add(parent);
+  }
+
+  return paths.join('.');
+};
+
 /**
  * Returns this sub-documents parent document.
  *

package/lib/validoptions.js

@@ -6,6 +6,7 @@
 'use strict';
 
 const VALID_OPTIONS = Object.freeze([
+  'allowDiskUse',
   'applyPluginsToChildSchemas',
   'applyPluginsToDiscriminators',
   'autoCreate',

package/lib/virtualtype.js

@@ -7,7 +7,7 @@ const utils = require('./utils');
  *
  * This is what mongoose uses to define virtual attributes via `Schema.prototype.virtual`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const fullname = schema.virtual('fullname');
  *     fullname instanceof mongoose.VirtualType // true
@@ -78,7 +78,7 @@ VirtualType.prototype.clone = function() {
  * - `virtual`: the virtual object you called `.get()` on
  * - `doc`: the document this virtual is attached to. Equivalent to `this`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const virtual = schema.virtual('fullname');
  *     virtual.get(function(value, virtual, doc) {
@@ -104,7 +104,7 @@ VirtualType.prototype.get = function(fn) {
  * - `virtual`: the virtual object you're calling `.set()` on
  * - `doc`: the document this virtual is attached to. Equivalent to `this`.
  *
- * ####Example:
+ * #### Example:
  *
  *     const virtual = schema.virtual('fullname');
  *     virtual.set(function(value, virtual, doc) {