mongoose 5.7.7 → 5.7.8

package/History.md

@@ -1,3 +1,14 @@
+5.7.8 / 2019-11-04
+==================
+ * fix(document): allow manually populating path within document array #8273
+ * fix(populate): update top-level `populated()` when updating document array with populated subpaths #8265
+ * fix(cursor): throw error when using aggregation cursor as async iterator #8280
+ * fix(schema): retain `_id: false` in schema after nesting in another schema #8274
+ * fix(document): make Document class an event emitter to support defining documents without models in node #8272
+ * docs: document return types for `.discriminator()` #8287
+ * docs(connection): add note about exporting schemas, not models, in multi connection paradigm #8275
+ * docs: clarify that transforms defined in `toObject()` options are applied to subdocs #8260
+
 5.7.7 / 2019-10-24
 ==================
  * fix(populate): make populate virtual consistently an empty array if local field is only empty arrays #8230

package/lib/aggregate.js

@@ -1011,20 +1011,20 @@ Aggregate.prototype.catch = function(reject) {
 
 /**
  * Returns an asyncIterator for use with [`for/await/of` loops](http://bit.ly/async-iterators)
- * This function *only* works for `find()` queries.
  * You do not need to call this function explicitly, the JavaScript runtime
  * will call it for you.
  *
  * ####Example
  *
- *     for await (const doc of Model.find().sort({ name: 1 })) {
+ *     const agg = Model.aggregate([{ $match: { age: { $gte: 25 } } }]);
+ *     for await (const doc of agg) {
  *       console.log(doc.name);
  *     }
  *
  * Node.js 10.x supports async iterators natively without any flags. You can
  * enable async iterators in Node.js 8.x using the [`--harmony_async_iteration` flag](https://github.com/tc39/proposal-async-iteration/issues/117#issuecomment-346695187).
  *
- * **Note:** This function is not if `Symbol.asyncIterator` is undefined. If
+ * **Note:** This function is not set if `Symbol.asyncIterator` is undefined. If
  * `Symbol.asyncIterator` is undefined, that means your Node.js version does not
  * support async iterators.
  *

package/lib/cursor/AggregationCursor.js

@@ -4,6 +4,7 @@
 
 'use strict';
 
+const MongooseError = require('../error/mongooseError');
 const Readable = require('stream').Readable;
 const eachAsync = require('../helpers/cursor/eachAsync');
 const util = require('util');
@@ -94,6 +95,15 @@ AggregationCursor.prototype._read = function() {
   });
 };
 
+if (Symbol.asyncIterator != null) {
+  const msg = 'Mongoose does not support using async iterators with an ' +
+    'existing aggregation cursor. See http://bit.ly/mongoose-async-iterate-aggregation';
+
+  AggregationCursor.prototype[Symbol.asyncIterator] = function() {
+    throw new MongooseError(msg);
+  };
+}
+
 /**
  * Registers a transform function which subsequently maps documents retrieved
  * via the streams interface or `.next()`

package/lib/document.js

@@ -184,6 +184,10 @@ utils.each(
 
 Document.prototype.constructor = Document;
 
+for (const i in EventEmitter.prototype) {
+  Document[i] = EventEmitter.prototype[i];
+}
+
 /**
  * The documents schema.
  *
@@ -1163,6 +1167,21 @@ Document.prototype.$set = function $set(path, val, type, options) {
       val = schema.applySetters(val, this, false, priorVal);
     }
 
+    if (schema.$isMongooseDocumentArray &&
+        Array.isArray(val) &&
+        val.length > 0 &&
+        val[0] != null &&
+        val[0].$__ != null &&
+        val[0].$__.populated != null) {
+      const populatedPaths = Object.keys(val[0].$__.populated);
+      for (const populatedPath of populatedPaths) {
+        this.populated(path + '.' + populatedPath,
+          val.map(v => v.populated(populatedPath)),
+          val[0].$__.populated[populatedPath].options);
+      }
+      didPopulate = true;
+    }
+
     if (!didPopulate && this.$__.populated) {
       delete this.$__.populated[path];
     }
@@ -2970,7 +2989,6 @@ Document.prototype.$toObject = function(options, json) {
  *
  * If you want to skip transformations, use `transform: false`:
  *
- *     if (!schema.options.toObject) schema.options.toObject = {};
  *     schema.options.toObject.hide = '_id';
  *     schema.options.toObject.transform = function (doc, ret, options) {
  *       if (options.hide) {
@@ -2986,7 +3004,26 @@ Document.prototype.$toObject = function(options, json) {
  *     doc.toObject({ hide: 'secret _id', transform: false });// { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
  *     doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }
  *
- * Transforms are applied _only to the document and are not applied to sub-documents_.
+ * If you pass a transform in `toObject()` options, Mongoose will apply the transform
+ * to [subdocuments](/docs/subdocs.html) in addition to the top-level document.
+ * Similarly, `transform: false` skips transforms for all subdocuments.
+ * Note that this is behavior is different for transforms defined in the schema:
+ * if you define a transform in `schema.options.toObject.transform`, that transform
+ * will **not** apply to subdocuments.
+ *
+ *     const memberSchema = new Schema({ name: String, email: String });
+ *     const groupSchema = new Schema({ members: [memberSchema], name: String, email });
+ *     const Group = mongoose.model('Group', groupSchema);
+ *
+ *     const doc = new Group({
+ *       name: 'Engineering',
+ *       email: 'dev@mongoosejs.io',
+ *       members: [{ name: 'Val', email: 'val@mongoosejs.io' }]
+ *     });
+ *
+ *     // Removes `email` from both top-level document **and** array elements
+ *     // { name: 'Engineering', members: [{ name: 'Val' }] }
+ *     doc.toObject({ transform: (doc, ret) => { delete ret.email; return ret; } });
  *
  * Transforms, like all of these options, are also available for `toJSON`. See [this guide to `JSON.stringify()`](https://thecodebarbarian.com/the-80-20-guide-to-json-stringify-in-javascript.html) to learn why `toJSON()` and `toObject()` are separate functions.
  *

package/lib/model.js

@@ -1067,6 +1067,7 @@ Model.exists = function exists(filter, options, callback) {
  * @param {String} name discriminator model name
  * @param {Schema} schema discriminator model schema
  * @param {String} [value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
+ * @return {Model} The newly created discriminator model
  * @api public
  */
 
@@ -1149,7 +1150,7 @@ for (const i in EventEmitter.prototype) {
  *
  * Mongoose calls this function automatically when a model is created using
  * [`mongoose.model()`](/docs/api.html#mongoose_Mongoose-model) or
- * * [`connection.model()`](/docs/api.html#connection_Connection-model), so you
+ * [`connection.model()`](/docs/api.html#connection_Connection-model), so you
  * don't need to call it. This function is also idempotent, so you may call it
  * to get back a promise that will resolve when your indexes are finished
  * building as an alternative to [`MyModel.on('index')`](/docs/guide.html#indexes)
@@ -3411,7 +3412,7 @@ Model.bulkWrite = function(ops, options, callback) {
  *     var mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });
  *
  * @param {Object} obj
- * @return {Model} document instance
+ * @return {Document} document instance
  * @api public
  */
 

package/lib/options/SchemaTypeOptions.js

@@ -107,7 +107,8 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'ref', opts);
 Object.defineProperty(SchemaTypeOptions.prototype, 'select', opts);
 
 /**
- * If truthy, Mongoose will build an index on this path when the model is
+ * If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), Mongoose will
+ * build an index on this path when the model is
  * compiled.
  *
  * @api public
@@ -120,7 +121,8 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'select', opts);
 Object.defineProperty(SchemaTypeOptions.prototype, 'index', opts);
 
 /**
- * If truthy, Mongoose will build a unique index on this path when the
+ * If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), Mongoose
+ * will build a unique index on this path when the
  * model is compiled. [The `unique` option is **not** a validator](/docs/validation.html#the-unique-option-is-not-a-validator).
  *
  * @api public
@@ -133,7 +135,8 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'index', opts);
 Object.defineProperty(SchemaTypeOptions.prototype, 'unique', opts);
 
 /**
- * If truthy, Mongoose will disallow changes to this path once the document
+ * If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), Mongoose will
+ * disallow changes to this path once the document
  * is saved to the database for the first time. Read more about [immutability in Mongoose here](http://thecodebarbarian.com/whats-new-in-mongoose-5-6-immutable-properties.html).
  *
  * @api public
@@ -146,7 +149,8 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'unique', opts);
 Object.defineProperty(SchemaTypeOptions.prototype, 'immutable', opts);
 
 /**
- * If truthy, Mongoose will build a sparse index on this path.
+ * If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), Mongoose will
+ * build a sparse index on this path.
  *
  * @api public
  * @property sparse
@@ -158,7 +162,8 @@ Object.defineProperty(SchemaTypeOptions.prototype, 'immutable', opts);
 Object.defineProperty(SchemaTypeOptions.prototype, 'sparse', opts);
 
 /**
- * If truthy, Mongoose will build a text index on this path.
+ * If [truthy](https://masteringjs.io/tutorials/fundamentals/truthy), Mongoose
+ * will build a text index on this path.
  *
  * @api public
  * @property text

package/lib/queryhelpers.js

@@ -107,7 +107,7 @@ exports.getDiscriminatorByValue = getDiscriminatorByValue;
  * @param {Object} doc
  * @param {Object} fields
  *
- * @return {Model}
+ * @return {Document}
  */
 exports.createModel = function createModel(model, doc, fields, userProvidedFields) {
   model.hooks.execPreSync('createModel', doc);

package/lib/schema/SingleNestedPath.js

@@ -280,6 +280,7 @@ SingleNestedPath.prototype.doValidateSync = function(value, scope, options) {
  * @param {String} name
  * @param {Schema} schema fields to add to the schema for instances of this sub-class
  * @param {String} [value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
+ * @return {Function} the constructor Mongoose will use for creating instances of this discriminator model
  * @see discriminators /docs/discriminators.html
  * @api public
  */

package/lib/schema/array.js

@@ -196,8 +196,8 @@ SchemaArray.prototype.checkRequired = function checkRequired(value, doc) {
  */
 
 SchemaArray.prototype.enum = function() {
-  let arr = this; /* eslint consistent-this: 0 */
-  while (true) { /* eslint no-constant-condition: 0 */
+  let arr = this;
+  while (true) {
     const instance = get(arr, 'caster.instance');
     if (instance === 'Array') {
       arr = arr.caster;

package/lib/schema/documentarray.js

@@ -9,6 +9,7 @@ const CastError = require('../error/cast');
 const EventEmitter = require('events').EventEmitter;
 const SchemaType = require('../schematype');
 const discriminator = require('../helpers/model/discriminator');
+const get = require('../helpers/get');
 const util = require('util');
 const utils = require('../utils');
 const getConstructor = require('../helpers/discriminator/getConstructor');
@@ -54,6 +55,17 @@ function DocumentArrayPath(key, schema, options, schemaOptions) {
       return arr;
     });
   }
+
+  const parentSchemaType = this;
+  this.$embeddedSchemaType = new SchemaType(key + '.$', {
+    required: get(this, 'schemaOptions.required', false)
+  });
+  this.$embeddedSchemaType.cast = function(value, doc, init) {
+    return parentSchemaType.cast(value, doc, init)[0];
+  };
+  this.$embeddedSchemaType.$isMongooseDocumentArrayElement = true;
+  this.$embeddedSchemaType.caster = this.Constructor;
+  this.$embeddedSchemaType.schema = this.schema;
 }
 
 /**
@@ -135,6 +147,7 @@ function _createConstructor(schema, options, baseClass) {
  * @param {Schema} schema fields to add to the schema for instances of this sub-class
  * @param {String} [value] the string stored in the `discriminatorKey` property. If not specified, Mongoose uses the `name` parameter.
  * @see discriminators /docs/discriminators.html
+ * @return {Function} the constructor Mongoose will use for creating instances of this discriminator model
  * @api public
  */
 

package/lib/schema.js

@@ -402,7 +402,6 @@ Schema.prototype.add = function add(obj, prefix) {
   // the `_id` option. This behavior never worked before 5.4.11 but numerous
   // codebases use it (see gh-7516, gh-7512).
   if (obj._id === false && prefix == null) {
-    delete obj._id;
     this.options._id = false;
   }
 
@@ -417,6 +416,10 @@ Schema.prototype.add = function add(obj, prefix) {
       throw new TypeError('Invalid value for schema path `' + fullPath +
         '`, got value "' + obj[key] + '"');
     }
+    // Retain `_id: false` but don't set it as a path, re: gh-8274.
+    if (key === '_id' && obj[key] === false) {
+      continue;
+    }
 
     if (Array.isArray(obj[key]) && obj[key].length === 1 && obj[key][0] == null) {
       throw new TypeError('Invalid value for schema Array path `' + fullPath +
@@ -1179,16 +1182,7 @@ function getPositionalPathType(self, path) {
 
     if (i === last && val && !/\D/.test(subpath)) {
       if (val.$isMongooseDocumentArray) {
-        const oldVal = val;
-        val = new SchemaType(subpath, {
-          required: get(val, 'schemaOptions.required', false)
-        });
-        val.cast = function(value, doc, init) {
-          return oldVal.cast(value, doc, init)[0];
-        };
-        val.$isMongooseDocumentArrayElement = true;
-        val.caster = oldVal.caster;
-        val.schema = oldVal.schema;
+        val = val.$embeddedSchemaType;
       } else if (val instanceof MongooseTypes.Array) {
         // StringSchema, NumberSchema, etc
         val = val.caster;
@@ -1637,8 +1631,8 @@ Schema.prototype.indexes = function() {
  * @param {String|Model} [options.ref] model name or model instance. Marks this as a [populate virtual](populate.html#populate-virtuals).
  * @param {String|Function} [options.localField] Required for populate virtuals. See [populate virtual docs](populate.html#populate-virtuals) for more information.
  * @param {String|Function} [options.foreignField] Required for populate virtuals. See [populate virtual docs](populate.html#populate-virtuals) for more information.
- * @param {Boolean|Function} [options.justOne=false] Only works with populate virtuals. If 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, this populate virtual will contain the number of documents rather than the documents themselves when you `populate()`.
+ * @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()`.
  * @return {VirtualType}
  */
 

package/lib/schematype.js

@@ -664,7 +664,7 @@ SchemaType.prototype.get = function(fn) {
  *     Product.on('error', handleError);
  *
  * @param {RegExp|Function|Object} obj validator function, or hash describing options
- * @param {Function} [obj.validator] validator function. If the validator function returns `undefined` or a truthy value, validation succeeds. If it returns falsy (except `undefined`) or throws an error, validation fails.
+ * @param {Function} [obj.validator] validator function. If the validator function returns `undefined` or a truthy value, validation succeeds. If it returns [falsy](https://masteringjs.io/tutorials/fundamentals/falsy) (except `undefined`) or throws an error, validation fails.
  * @param {String|Function} [obj.message] optional error message. If function, should return the error message as a string
  * @param {Boolean} [obj.propsParameter=false] If true, Mongoose will pass the validator properties object (with the `validator` function, `message`, etc.) as the 2nd arg to the validator function. This is disabled by default because many validators [rely on positional args](https://github.com/chriso/validator.js#validators), so turning this on may cause unpredictable behavior in external validators.
  * @param {String|Function} [errorMsg] optional error message. If function, should return the error message as a string
@@ -1265,7 +1265,7 @@ SchemaType._isRef = function(self, value, doc, init) {
     // - setting / pushing values after population
     const path = doc.$__fullPath(self.path);
     const owner = doc.ownerDocument ? doc.ownerDocument() : doc;
-    ref = owner.populated(path);
+    ref = owner.populated(path) || doc.populated(self.path);
   }
 
   if (ref) {

package/lib/types/core_array.js

@@ -634,24 +634,6 @@ class CoreMongooseArray extends Array {
       undefined, { skipDocumentArrayCast: true });
     const ret = [].push.apply(this, values);
 
-    // If this is a document array, each element may contain single
-    // populated paths, so we need to modify the top-level document's
-    // populated cache. See gh-8247.
-    if (this.isMongooseDocumentArray && parent.$__.populated != null) {
-      const populatedPaths = Object.keys(parent.$__.populated).
-        filter(p => p.startsWith(this[arrayPathSymbol] + '.'));
-
-      for (const path of populatedPaths) {
-        const remnant = path.slice((this[arrayPathSymbol] + '.').length);
-        if (!Array.isArray(parent.$__.populated[path].value)) {
-          continue;
-        }
-        for (const val of values) {
-          parent.$__.populated[path].value.push(val.populated(remnant));
-        }
-      }
-    }
-
     this._registerAtomic('$push', values);
     this._markModified();
     return ret;

package/lib/types/documentarray.js

@@ -172,6 +172,64 @@ class CoreDocumentArray extends CoreMongooseArray {
     }));
   }
 
+  /**
+   * Wraps [`Array#push`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/push) with proper change tracking.
+   *
+   * @param {Object} [args...]
+   * @api public
+   * @method push
+   * @memberOf MongooseDocumentArray
+   */
+
+  push() {
+    const ret = super.push.apply(this, arguments);
+
+    _updateParentPopulated(this);
+
+    return ret;
+  }
+
+  /**
+   * Pulls items from the array atomically.
+   *
+   * @param {Object} [args...]
+   * @api public
+   * @method pull
+   * @memberOf MongooseDocumentArray
+   */
+
+  pull() {
+    const ret = super.pull.apply(this, arguments);
+
+    _updateParentPopulated(this);
+
+    return ret;
+  }
+
+  /**
+   * Wraps [`Array#shift`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/unshift) with proper change tracking.
+   */
+
+  shift() {
+    const ret = super.shift.apply(this, arguments);
+
+    _updateParentPopulated(this);
+
+    return ret;
+  }
+
+  /**
+   * Wraps [`Array#splice`](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/splice) with proper change tracking and casting.
+   */
+
+  splice() {
+    const ret = super.splice.apply(this, arguments);
+
+    _updateParentPopulated(this);
+
+    return ret;
+  }
+
   /**
    * Helper for console.log
    *
@@ -254,6 +312,29 @@ if (util.inspect.custom) {
     CoreDocumentArray.prototype.inspect;
 }
 
+/*!
+ * If this is a document array, each element may contain single
+ * populated paths, so we need to modify the top-level document's
+ * populated cache. See gh-8247, gh-8265.
+ */
+
+function _updateParentPopulated(arr) {
+  const parent = arr[arrayParentSymbol];
+  if (parent.$__.populated != null) {
+    const populatedPaths = Object.keys(parent.$__.populated).
+      filter(p => p.startsWith(arr[arrayPathSymbol] + '.'));
+
+    for (const path of populatedPaths) {
+      const remnant = path.slice((arr[arrayPathSymbol] + '.').length);
+      if (!Array.isArray(parent.$__.populated[path].value)) {
+        continue;
+      }
+
+      parent.$__.populated[path].value = arr.map(val => val.populated(remnant));
+    }
+  }
+}
+
 /**
  * DocumentArray constructor
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongoose",
   "description": "Mongoose MongoDB ODM",
-  "version": "5.7.7",
+  "version": "5.7.8",
   "author": "Guillermo Rauch <guillermo@learnboost.com>",
   "keywords": [
     "mongodb",
@@ -102,10 +102,6 @@
     },
     "rules": {
       "comma-style": "error",
-      "consistent-this": [
-        "error",
-        "_this"
-      ],
       "indent": [
         "error",
         2,
@@ -118,6 +114,7 @@
       "no-buffer-constructor": "warn",
       "no-console": "off",
       "no-multi-spaces": "error",
+      "no-constant-condition": "off",
       "func-call-spacing": "error",
       "no-trailing-spaces": "error",
       "quotes": [