mongoose 6.2.9 → 6.3.0

package/lib/schema.js

@@ -22,6 +22,7 @@ const readPref = require('./driver').get().ReadPreference;
 const setupTimestamps = require('./helpers/timestamps/setupTimestamps');
 const utils = require('./utils');
 const validateRef = require('./helpers/populate/validateRef');
+const util = require('util');
 
 let MongooseTypes;
 
@@ -38,7 +39,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 +48,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 +78,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 +232,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 +254,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 +271,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 +289,7 @@ Schema.prototype.paths;
 /**
  * Schema as a tree
  *
- * ####Example:
+ * #### Example:
  *     {
  *         '_id'     : ObjectId
  *       , 'nested'  : {
@@ -307,7 +308,7 @@ Schema.prototype.tree;
 /**
  * Returns a deep copy of the schema
  *
- * ####Example:
+ * #### Example:
  *
  *     const schema = new Schema({ name: String });
  *     const clone = schema.clone();
@@ -370,6 +371,9 @@ Schema.prototype._clone = function _clone(Constructor) {
   if (this.discriminators != null) {
     s.discriminators = Object.assign({}, this.discriminators);
   }
+  if (this._applyDiscriminators != null) {
+    s._applyDiscriminators = Object.assign({}, this._applyDiscriminators);
+  }
 
   s.aliases = Object.assign({}, this.aliases);
 
@@ -381,7 +385,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`,
@@ -469,10 +473,15 @@ Schema.prototype.defaultOptions = function(options) {
   return options;
 };
 
+Schema.prototype.discriminator = function(name, schema) {
+  this._applyDiscriminators = {};
+  this._applyDiscriminators[name] = schema;
+};
+
 /**
  * Adds key path / schema type pairs to this schema.
  *
- * ####Example:
+ * #### Example:
  *
  *     const ToySchema = new Schema();
  *     ToySchema.add({ name: 'string', color: 'string', price: 'number' });
@@ -510,7 +519,6 @@ Schema.prototype.add = function add(obj, prefix) {
 
   const keys = Object.keys(obj);
   const typeKey = this.options.typeKey;
-
   for (const key of keys) {
     const fullPath = prefix + key;
     const val = obj[key];
@@ -540,6 +548,25 @@ Schema.prototype.add = function add(obj, prefix) {
         this.nested[prefix.substring(0, prefix.length - 1)] = true;
       }
       this.path(prefix + key, val);
+      if (val[0] != null && !(val[0].instanceOfSchema) && utils.isPOJO(val[0].discriminators)) {
+        const schemaType = this.path(prefix + key);
+        for (const key in val[0].discriminators) {
+          schemaType.discriminator(key, val[0].discriminators[key]);
+        }
+      } else if (val[0] != null && val[0].instanceOfSchema && utils.isPOJO(val[0]._applyDiscriminators)) {
+        const applyDiscriminators = val[0]._applyDiscriminators || [];
+        const schemaType = this.path(prefix + key);
+        for (const disc in applyDiscriminators) {
+          schemaType.discriminator(disc, applyDiscriminators[disc]);
+        }
+      }
+      else if (val != null && val.instanceOfSchema && utils.isPOJO(val._applyDiscriminators)) {
+        const applyDiscriminators = val._applyDiscriminators || [];
+        const schemaType = this.path(prefix + key);
+        for (const disc in applyDiscriminators) {
+          schemaType.discriminator(disc, applyDiscriminators[disc]);
+        }
+      }
     } else if (Object.keys(val).length < 1) {
       // Special-case: {} always interpreted as Mixed path so leaf at this node
       if (prefix) {
@@ -569,6 +596,12 @@ Schema.prototype.add = function add(obj, prefix) {
           this.nested[prefix.substring(0, prefix.length - 1)] = true;
         }
         this.path(prefix + key, val);
+        if (val != null && !(val.instanceOfSchema) && utils.isPOJO(val.discriminators)) {
+          const schemaType = this.path(prefix + key);
+          for (const key in val.discriminators) {
+            schemaType.discriminator(key, val.discriminators[key]);
+          }
+        }
       }
     }
   }
@@ -579,6 +612,86 @@ Schema.prototype.add = function add(obj, prefix) {
   return this;
 };
 
+/**
+ * Remove an index by name or index specification.
+ *
+ * removeIndex only removes indexes from your schema object. Does **not** affect the indexes
+ * in MongoDB.
+ *
+ * ####Example:
+ *
+ *     const ToySchema = new Schema({ name: String, color: String, price: Number });
+ *
+ *     // Add a new index on { name, color }
+ *     ToySchema.index({ name: 1, color: 1 });
+ *
+ *     // Remove index on { name, color }
+ *     // Keep in mind that order matters! `removeIndex({ color: 1, name: 1 })` won't remove the index
+ *     ToySchema.removeIndex({ name: 1, color: 1 });
+ *
+ *     // Add an index with a custom name
+ *     ToySchema.index({ color: 1 }, { name: 'my custom index name' });
+ *     // Remove index by name
+ *     ToySchema.removeIndex('my custom index name');
+ *
+ * @param {Object|string} index name or index specification
+ * @return {Schema} the Schema instance
+ * @api public
+ */
+
+Schema.prototype.removeIndex = function removeIndex(index) {
+  if (arguments.length > 1) {
+    throw new Error('removeIndex() takes only 1 argument');
+  }
+
+  if (typeof index !== 'object' && typeof index !== 'string') {
+    throw new Error('removeIndex() may only take either an object or a string as an argument');
+  }
+
+  if (typeof index === 'object') {
+    for (let i = this._indexes.length - 1; i >= 0; --i) {
+      if (util.isDeepStrictEqual(this._indexes[i][0], index)) {
+        this._indexes.splice(i, 1);
+      }
+    }
+  } else {
+    for (let i = this._indexes.length - 1; i >= 0; --i) {
+      if (this._indexes[i][1] != null && this._indexes[i][1].name === index) {
+        this._indexes.splice(i, 1);
+      }
+    }
+  }
+
+  return this;
+};
+
+/**
+ * Remove all indexes from this schema.
+ *
+ * clearIndexes only removes indexes from your schema object. Does **not** affect the indexes
+ * in MongoDB.
+ *
+ * ####Example:
+ *
+ *     const ToySchema = new Schema({ name: String, color: String, price: Number });
+ *     ToySchema.index({ name: 1 });
+ *     ToySchema.index({ color: 1 });
+ *
+ *     // Remove all indexes on this schema
+ *     ToySchema.clearIndexes();
+ *
+ *     ToySchema.indexes(); // []
+ *
+ * @return {Schema} the Schema instance
+ * @api public
+ */
+
+Schema.prototype.clearIndexes = function clearIndexes() {
+  this._indexes.length = 0;
+
+  return this;
+};
+
 /**
  * Reserved document keys.
  *
@@ -646,7 +759,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
@@ -1010,6 +1123,7 @@ Schema.prototype.interpretAsType = function(path, obj, options) {
         if (options.hasOwnProperty('strict')) {
           childSchemaOptions.strict = options.strict;
         }
+
         if (this._userProvidedOptions.hasOwnProperty('_id')) {
           childSchemaOptions._id = this._userProvidedOptions._id;
         } else if (Schema.Types.DocumentArray.defaultOptions._id != null) {
@@ -1133,7 +1247,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 +1276,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 +1328,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 +1485,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 +1506,7 @@ Schema.prototype.queue = function(name, args) {
 /**
  * Defines a pre hook for the model.
  *
- * ####Example
+ * #### Example
  *
  *     const toySchema = new Schema({ name: String, created: Date });
  *
@@ -1466,7 +1580,7 @@ Schema.prototype.pre = function(name) {
  *     });
  *
  *     schema.post(/Many$/, function(res) {
- *       console.log('this fired after you ran `updateMany()` or `deleteMany()`);
+ *       console.log('this fired after you ran `updateMany()` or `deleteMany()`');
  *     });
  *
  *     const Model = mongoose.model('Model', schema);
@@ -1514,7 +1628,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 +1662,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 +1709,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 +1742,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 +1767,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 +1816,7 @@ Schema.prototype.set = function(key, value, _tags) {
 /**
  * Gets a schema option.
  *
- * ####Example:
+ * #### Example:
  *
  *     schema.get('strict'); // true
  *     schema.set('strict', false);
@@ -1740,7 +1854,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 +2016,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 +2083,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 +2346,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)