mongoose 6.5.2 → 6.5.5

package/lib/error/validation.js

@@ -41,15 +41,19 @@ class ValidationError extends MongooseError {
     return this.name + ': ' + _generateMessage(this);
   }
 
-  /*!
+  /**
    * inspect helper
+   * @api private
    */
   inspect() {
     return Object.assign(new Error(this.message), this);
   }
 
-  /*!
+  /**
   * add message
+  * @param {String} path
+  * @param {String|Error} error
+  * @api private
   */
   addError(path, error) {
     if (error instanceof ValidationError) {
@@ -68,16 +72,14 @@ class ValidationError extends MongooseError {
 
 
 if (util.inspect.custom) {
-  /*!
-  * Avoid Node deprecation warning DEP0079
-  */
-
+  // Avoid Node deprecation warning DEP0079
   ValidationError.prototype[util.inspect.custom] = ValidationError.prototype.inspect;
 }
 
-/*!
+/**
  * Helper for JSON.stringify
  * Ensure `name` and `message` show up in toJSON output re: gh-9847
+ * @api private
  */
 Object.defineProperty(ValidationError.prototype, 'toJSON', {
   enumerable: false,

package/lib/error/validator.js

@@ -31,16 +31,18 @@ class ValidatorError extends MongooseError {
     this.reason = properties.reason;
   }
 
-  /*!
+  /**
    * toString helper
    * TODO remove? This defaults to `${this.name}: ${this.message}`
+   * @api private
    */
   toString() {
     return this.message;
   }
 
-  /*!
+  /**
    * Ensure `name` and `message` show up in toJSON output re: gh-9296
+   * @api private
    */
 
   toJSON() {
@@ -53,9 +55,10 @@ Object.defineProperty(ValidatorError.prototype, 'name', {
   value: 'ValidatorError'
 });
 
-/*!
+/**
  * The object used to define this validator. Not enumerable to hide
  * it from `require('util').inspect()` output re: gh-3925
+ * @api private
  */
 
 Object.defineProperty(ValidatorError.prototype, 'properties', {
@@ -67,8 +70,9 @@ Object.defineProperty(ValidatorError.prototype, 'properties', {
 // Exposed for testing
 ValidatorError.prototype.formatMessage = formatMessage;
 
-/*!
+/**
  * Formats error messages
+ * @api private
  */
 
 function formatMessage(msg, properties) {

package/lib/helpers/clone.js

@@ -12,7 +12,7 @@ const trustedSymbol = require('./query/trusted').trustedSymbol;
 const utils = require('../utils');
 
 
-/*!
+/**
  * Object clone with Mongoose natives support.
  *
  * If options.minimize is true, creates a minimal data object. Empty objects and undefined values will not be cloned. This makes the data payload sent to MongoDB as small as possible.

package/lib/helpers/discriminator/getConstructor.js

@@ -2,8 +2,9 @@
 
 const getDiscriminatorByValue = require('./getDiscriminatorByValue');
 
-/*!
+/**
  * Find the correct constructor, taking into account discriminators
+ * @api private
  */
 
 module.exports = function getConstructor(Constructor, value) {

package/lib/helpers/discriminator/getDiscriminatorByValue.js

@@ -2,12 +2,13 @@
 
 const areDiscriminatorValuesEqual = require('./areDiscriminatorValuesEqual');
 
-/*!
-* returns discriminator by discriminatorMapping.value
-*
-* @param {Model} model
-* @param {string} value
-*/
+/**
+ * returns discriminator by discriminatorMapping.value
+ *
+ * @param {Object} discriminators
+ * @param {string} value
+ * @api private
+ */
 
 module.exports = function getDiscriminatorByValue(discriminators, value) {
   if (discriminators == null) {

package/lib/helpers/discriminator/getSchemaDiscriminatorByValue.js

@@ -2,12 +2,13 @@
 
 const areDiscriminatorValuesEqual = require('./areDiscriminatorValuesEqual');
 
-/*!
-* returns discriminator by discriminatorMapping.value
-*
-* @param {Schema} schema
-* @param {string} value
-*/
+/**
+ * returns discriminator by discriminatorMapping.value
+ *
+ * @param {Schema} schema
+ * @param {string} value
+ * @api private
+ */
 
 module.exports = function getSchemaDiscriminatorByValue(schema, value) {
   if (schema == null || schema.discriminators == null) {

package/lib/helpers/document/compile.js

@@ -24,8 +24,13 @@ const _isEmptyOptions = Object.freeze({
   transform: false
 });
 
-/*!
+/**
  * Compiles schemas.
+ * @param {Object} tree
+ * @param {Any} proto
+ * @param {String} prefix
+ * @param {Object} options
+ * @api private
  */
 
 function compile(tree, proto, prefix, options) {
@@ -44,8 +49,15 @@ function compile(tree, proto, prefix, options) {
   }
 }
 
-/*!
+/**
  * Defines the accessor named prop on the incoming prototype.
+ * @param {Object} options
+ * @param {String} options.prop
+ * @param {Boolean} options.subprops
+ * @param {Any} options.prototype
+ * @param {String} [options.prefix]
+ * @param {Object} options.options
+ * @api private
  */
 
 function defineKey({ prop, subprops, prototype, prefix, options }) {

package/lib/helpers/document/getEmbeddedDiscriminatorPath.js

@@ -3,9 +3,13 @@
 const get = require('../get');
 const getSchemaDiscriminatorByValue = require('../discriminator/getSchemaDiscriminatorByValue');
 
-/*!
+/**
  * Like `schema.path()`, except with a document, because impossible to
  * determine path type without knowing the embedded discriminator key.
+ * @param {Document} doc
+ * @param {String} path
+ * @param {Object} [options]
+ * @api private
  */
 
 module.exports = function getEmbeddedDiscriminatorPath(doc, path, options) {

package/lib/helpers/get.js

@@ -1,8 +1,9 @@
 'use strict';
 
-/*!
+/**
  * Simplified lodash.get to work around the annoying null quirk. See:
  * https://github.com/lodash/lodash/issues/3659
+ * @api private
  */
 
 module.exports = function get(obj, path, def) {

package/lib/helpers/getConstructorName.js

@@ -1,7 +1,8 @@
 'use strict';
 
-/*!
+/**
  * If `val` is an object, returns constructor name, if possible. Otherwise returns undefined.
+ * @api private
  */
 
 module.exports = function getConstructorName(val) {

package/lib/helpers/indexes/isIndexEqual.js

@@ -6,13 +6,13 @@ const utils = require('../../utils');
  * Given a Mongoose index definition (key + options objects) and a MongoDB server
  * index definition, determine if the two indexes are equal.
  *
- * @param {Object} key the Mongoose index spec
+ * @param {Object} schemaIndexKeysObject the Mongoose index spec
  * @param {Object} options the Mongoose index definition's options
  * @param {Object} dbIndex the index in MongoDB as returned by `listIndexes()`
  * @api private
  */
 
-module.exports = function isIndexEqual(key, options, dbIndex) {
+module.exports = function isIndexEqual(schemaIndexKeysObject, options, dbIndex) {
   // Special case: text indexes have a special format in the db. For example,
   // `{ name: 'text' }` becomes:
   // {
@@ -30,11 +30,11 @@ module.exports = function isIndexEqual(key, options, dbIndex) {
     delete dbIndex.key._fts;
     delete dbIndex.key._ftsx;
     const weights = { ...dbIndex.weights, ...dbIndex.key };
-    if (Object.keys(weights).length !== Object.keys(key).length) {
+    if (Object.keys(weights).length !== Object.keys(schemaIndexKeysObject).length) {
       return false;
     }
     for (const prop of Object.keys(weights)) {
-      if (!(prop in key)) {
+      if (!(prop in schemaIndexKeysObject)) {
         return false;
       }
       const weight = weights[prop];
@@ -78,7 +78,7 @@ module.exports = function isIndexEqual(key, options, dbIndex) {
     }
   }
 
-  const schemaIndexKeys = Object.keys(key);
+  const schemaIndexKeys = Object.keys(schemaIndexKeysObject);
   const dbIndexKeys = Object.keys(dbIndex.key);
   if (schemaIndexKeys.length !== dbIndexKeys.length) {
     return false;
@@ -87,7 +87,7 @@ module.exports = function isIndexEqual(key, options, dbIndex) {
     if (schemaIndexKeys[i] !== dbIndexKeys[i]) {
       return false;
     }
-    if (!utils.deepEqual(key[schemaIndexKeys[i]], dbIndex.key[dbIndexKeys[i]])) {
+    if (!utils.deepEqual(schemaIndexKeysObject[schemaIndexKeys[i]], dbIndex.key[dbIndexKeys[i]])) {
       return false;
     }
   }

package/lib/helpers/isBsonType.js

@@ -1,7 +1,8 @@
 'use strict';
 
-/*!
+/**
  * Get the bson type, if it exists
+ * @api private
  */
 
 function isBsonType(obj, typename) {

package/lib/helpers/isMongooseObject.js

@@ -1,12 +1,12 @@
 'use strict';
 
 const isMongooseArray = require('../types/array/isMongooseArray').isMongooseArray;
-/*!
+/**
  * Returns if `v` is a mongoose object that has a `toObject()` method we can use.
  *
  * This is for compatibility with libs like Date.js which do foolish things to Natives.
  *
- * @param {any} v
+ * @param {Any} v
  * @api private
  */
 

package/lib/helpers/isObject.js

@@ -1,6 +1,6 @@
 'use strict';
 
-/*!
+/**
  * Determines if `arg` is an object.
  *
  * @param {Object|Array|String|Function|RegExp|any} arg

package/lib/helpers/isSimpleValidator.js

@@ -1,6 +1,6 @@
 'use strict';
 
-/*!
+/**
  * Determines if `arg` is a flat object.
  *
  * @param {Object|Array|String|Function|RegExp|any} arg

package/lib/helpers/model/applyHooks.js

@@ -23,10 +23,18 @@ applyHooks.middlewareFunctions = [
 ];
 
 /*!
+ * ignore
+ */
+
+const alreadyHookedFunctions = new Set(applyHooks.middlewareFunctions.flatMap(fn => ([fn, `$__${fn}`])));
+
+/**
  * Register hooks for this model
  *
  * @param {Model} model
  * @param {Schema} schema
+ * @param {Object} options
+ * @api private
  */
 
 function applyHooks(model, schema, options) {
@@ -115,6 +123,9 @@ function applyHooks(model, schema, options) {
     checkForPromise: true
   });
   for (const method of customMethods) {
+    if (alreadyHookedFunctions.has(method)) {
+      continue;
+    }
     if (!middleware.hasHooks(method)) {
       // Don't wrap if there are no hooks for the custom method to avoid
       // surprises. Also, `createWrapper()` enforces consistent async,

package/lib/helpers/model/applyMethods.js

@@ -3,11 +3,12 @@
 const get = require('../get');
 const utils = require('../../utils');
 
-/*!
+/**
  * Register methods for this model
  *
  * @param {Model} model
  * @param {Schema} schema
+ * @api private
  */
 
 module.exports = function applyMethods(model, schema) {
@@ -29,6 +30,15 @@ module.exports = function applyMethods(model, schema) {
       throw new Error('You have a method and a property in your schema both ' +
         'named "' + method + '"');
     }
+
+    // Avoid making custom methods if user sets a method to itself, e.g.
+    // `schema.method(save, Document.prototype.save)`. Can happen when
+    // calling `loadClass()` with a class that `extends Document`. See gh-12254
+    if (typeof fn === 'function' && model.prototype[method] === fn) {
+      delete schema.methods[method];
+      continue;
+    }
+
     if (schema.reserved[method] &&
         !get(schema, `methodOptions.${method}.suppressWarning`, false)) {
       utils.warn(`mongoose: the method name "${method}" is used by mongoose ` +

package/lib/helpers/model/applyStatics.js

@@ -1,9 +1,10 @@
 'use strict';
 
-/*!
+/**
  * Register statics for this model
  * @param {Model} model
  * @param {Schema} schema
+ * @api private
  */
 module.exports = function applyStatics(model, schema) {
   for (const i in schema.statics) {

package/lib/helpers/model/castBulkWrite.js

@@ -7,9 +7,13 @@ const cast = require('../../cast');
 const castUpdate = require('../query/castUpdate');
 const setDefaultsOnInsert = require('../setDefaultsOnInsert');
 
-/*!
+/**
  * Given a model and a bulkWrite op, return a thunk that handles casting and
  * validating the individual op.
+ * @param {Model} originalModel
+ * @param {Object} op
+ * @param {Object} [options]
+ * @api private
  */
 
 module.exports = function castBulkWrite(originalModel, op, options) {
@@ -222,8 +226,9 @@ function _addDiscriminatorToObject(schema, obj) {
   }
 }
 
-/*!
+/**
  * gets discriminator model if discriminator key is present in object
+ * @api private
  */
 
 function decideModelByObject(model, object) {

package/lib/helpers/model/discriminator.js

@@ -9,7 +9,9 @@ const CUSTOMIZABLE_DISCRIMINATOR_OPTIONS = {
   toJSON: true,
   toObject: true,
   _id: true,
-  id: true
+  id: true,
+  virtuals: true,
+  methods: true
 };
 
 /*!

package/lib/helpers/path/flattenObjectWithDottedPaths.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const MongooseError = require('../../error/mongooseError');
+const isMongooseObject = require('../isMongooseObject');
 const setDottedPath = require('../path/setDottedPath');
 const util = require('util');
 
@@ -13,8 +14,8 @@ module.exports = function flattenObjectWithDottedPaths(obj) {
   if (obj == null || typeof obj !== 'object' || Array.isArray(obj)) {
     return;
   }
-  // Avoid Mongoose docs
-  if (obj.$__) {
+  // Avoid Mongoose docs, like docs and maps, because these may cause infinite recursion
+  if (isMongooseObject(obj)) {
     return;
   }
   const keys = Object.keys(obj);

package/lib/helpers/pluralize.js

@@ -71,7 +71,7 @@ exports.uncountables = [
 ];
 const uncountables = exports.uncountables;
 
-/*!
+/**
  * Pluralize function.
  *
  * @author TJ Holowaychuk (extracted from _ext.js_)

package/lib/helpers/populate/assignRawDocsToIdStructure.js

@@ -6,7 +6,7 @@ const utils = require('../../utils');
 
 module.exports = assignRawDocsToIdStructure;
 
-/*!
+/**
  * Assign `vals` returned by mongo query to the `rawIds`
  * structure returned from utils.getVals() honoring
  * query sort order if specified by user.
@@ -21,8 +21,10 @@ module.exports = assignRawDocsToIdStructure;
  *   else documents are put back in original order of array if found in results
  *
  * @param {Array} rawIds
- * @param {Array} vals
- * @param {Boolean} sort
+ * @param {Array} resultDocs
+ * @param {Array} resultOrder
+ * @param {Object} options
+ * @param {Boolean} recursed
  * @api private
  */
 

package/lib/helpers/populate/assignVals.js

@@ -212,7 +212,7 @@ function numDocs(v) {
   return v == null ? 0 : 1;
 }
 
-/*!
+/**
  * 1) Apply backwards compatible find/findOne behavior to sub documents
  *
  *    find logic:
@@ -228,6 +228,12 @@ function numDocs(v) {
  * background:
  * _ids are left in the query even when user excludes them so
  * that population mapping can occur.
+ * @param {Any} val
+ * @param {Object} assignmentOpts
+ * @param {Object} populateOptions
+ * @param {Function} [populateOptions.transform]
+ * @param {Boolean} allIds
+ * @api private
  */
 
 function valueFilter(val, assignmentOpts, populateOptions, allIds) {
@@ -288,8 +294,11 @@ function valueFilter(val, assignmentOpts, populateOptions, allIds) {
   return val == null ? transform(val, allIds) : transform(null, allIds);
 }
 
-/*!
+/**
  * Remove _id from `subdoc` if user specified "lean" query option
+ * @param {Document} subdoc
+ * @param {Object} assignmentOpts
+ * @api private
  */
 
 function maybeRemoveId(subdoc, assignmentOpts) {
@@ -302,9 +311,11 @@ function maybeRemoveId(subdoc, assignmentOpts) {
   }
 }
 
-/*!
+/**
  * Determine if `obj` is something we can set a populated path to. Can be a
  * document, a lean document, or an array/map that contains docs.
+ * @param {Any} obj
+ * @api private
  */
 
 function isPopulatedObject(obj) {

package/lib/helpers/populate/createPopulateQueryFilter.js

@@ -44,9 +44,13 @@ module.exports = function createPopulateQueryFilter(ids, _match, _foreignField,
   return match;
 };
 
-/*!
+/**
  * Optionally filter out invalid ids that don't conform to foreign field's schema
  * to avoid cast errors (gh-7706)
+ * @param {Array} ids
+ * @param {SchemaType} foreignSchemaType
+ * @param {Boolean} [skipInvalidIds]
+ * @api private
  */
 
 function _filterInvalidIds(ids, foreignSchemaType, skipInvalidIds) {
@@ -64,9 +68,11 @@ function _filterInvalidIds(ids, foreignSchemaType, skipInvalidIds) {
   });
 }
 
-/*!
+/**
  * Format `mod.match` given that it may be an array that we need to $or if
  * the client has multiple docs with match functions
+ * @param {Array|Any} match
+ * @api private
  */
 
 function _formatMatch(match) {

package/lib/helpers/populate/getModelsMapForPopulate.js

@@ -15,6 +15,7 @@ const utils = require('../../utils');
 const modelSymbol = require('../symbols').modelSymbol;
 const populateModelSymbol = require('../symbols').populateModelSymbol;
 const schemaMixedSymbol = require('../../schema/symbols').schemaMixedSymbol;
+const StrictPopulate = require('../../error/strictPopulate');
 
 module.exports = function getModelsMapForPopulate(model, docs, options) {
   let doc;
@@ -44,9 +45,7 @@ module.exports = function getModelsMapForPopulate(model, docs, options) {
   allSchemaTypes = Array.isArray(allSchemaTypes) ? allSchemaTypes : [allSchemaTypes].filter(v => v != null);
 
   if (allSchemaTypes.length === 0 && options.strictPopulate !== false && options._localModel != null) {
-    return new MongooseError('Cannot populate path `' + (options._fullPath || options.path) +
-      '` because it is not in your schema. Set the `strictPopulate` option ' +
-      'to false to override.');
+    return new StrictPopulate(options._fullPath || options.path);
   }
 
   for (let i = 0; i < len; i++) {
@@ -625,11 +624,13 @@ function _getLocalFieldValues(doc, localField, model, options, virtual, schema)
   }
 }
 
-/*!
+/**
  * Retrieve the _id of `val` if a Document or Array of Documents.
  *
  * @param {Array|Document|Any} val
+ * @param {Schema} schema
  * @return {Array|Document|Any}
+ * @api private
  */
 
 function convertTo_id(val, schema) {

package/lib/helpers/populate/getSchemaTypes.js

@@ -12,15 +12,17 @@ const mpath = require('mpath');
 
 const populateModelSymbol = require('../symbols').populateModelSymbol;
 
-/*!
+/**
  * Given a model and its schema, find all possible schema types for `path`,
  * including searching through discriminators. If `doc` is specified, will
  * use the doc's values for discriminator keys when searching, otherwise
  * will search all discriminators.
  *
+ * @param {Model} model
  * @param {Schema} schema
  * @param {Object} doc POJO
  * @param {string} path
+ * @api private
  */
 
 module.exports = function getSchemaTypes(model, schema, doc, path) {

package/lib/helpers/populate/markArraySubdocsPopulated.js

@@ -2,7 +2,7 @@
 
 const utils = require('../../utils');
 
-/*!
+/**
  * If populating a path within a document array, make sure each
  * subdoc within the array knows its subpaths are populated.
  *
@@ -10,6 +10,10 @@ const utils = require('../../utils');
  *
  *     const doc = await Article.findOne().populate('comments.author');
  *     doc.comments[0].populated('author'); // Should be set
+ *
+ * @param {Document} doc
+ * @param {Object} [populated]
+ * @api private
  */
 
 module.exports = function markArraySubdocsPopulated(doc, populated) {

package/lib/helpers/projection/hasIncludedChildren.js

@@ -1,6 +1,6 @@
 'use strict';
 
-/*!
+/**
  * Creates an object that precomputes whether a given path has child fields in
  * the projection.
  *
@@ -11,6 +11,9 @@
  *     res['a.b']; // 1
  *     res['a.b.c']; // 1
  *     res['a.c']; // undefined
+ *
+ * @param {Object} fields
+ * @api private
  */
 
 module.exports = function hasIncludedChildren(fields) {

package/lib/helpers/projection/isPathExcluded.js

@@ -2,12 +2,13 @@
 
 const isDefiningProjection = require('./isDefiningProjection');
 
-/*!
+/**
  * Determines if `path` is excluded by `projection`
  *
  * @param {Object} projection
- * @param {string} path
+ * @param {String} path
  * @return {Boolean}
+ * @api private
  */
 
 module.exports = function isPathExcluded(projection, path) {