mongoose 6.4.3 → 6.4.6

package/lib/query.js

@@ -170,7 +170,7 @@ Query.base = mquery.prototype;
  * @default true
  * @property use$geoWithin
  * @memberOf Query
- * @receiver Query
+ * @static
  * @api public
  */
 
@@ -179,7 +179,7 @@ Query.use$geoWithin = mquery.use$geoWithin;
 /**
  * Converts this query to a customized, reusable query constructor with all arguments and options retained.
  *
- * #### Example
+ * #### Example:
  *
  *     // Create a query for adventure movies and read from the primary
  *     // node in the replica-set unless it is down, in which case we'll
@@ -309,7 +309,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a javascript function or expression to pass to MongoDBs query system.
  *
- * #### Example
+ * #### Example:
  *
  *     query.$where('this.comments.length === 10 || this.name.length === 5')
  *
@@ -337,7 +337,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a `path` for use with chaining.
  *
- * #### Example
+ * #### Example:
  *
  *     // instead of writing:
  *     User.find({age: {$gte: 21, $lte: 65}}, callback);
@@ -367,7 +367,7 @@ Query.prototype.clone = function clone() {
 /**
  * Specifies a `$slice` projection for an array.
  *
- * #### Example
+ * #### Example:
  *
  *     query.slice('comments', 5);
  *     query.slice('comments', -5);
@@ -445,7 +445,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies the complementary comparison value for paths specified with `where()`
  *
- * #### Example
+ * #### Example:
  *
  *     User.where('age').equals(49);
  *
@@ -464,7 +464,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for an `$or` condition.
  *
- * #### Example
+ * #### Example:
  *
  *     query.or([{ color: 'red' }, { status: 'emergency' }]);
  *
@@ -480,7 +480,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for a `$nor` condition.
  *
- * #### Example
+ * #### Example:
  *
  *     query.nor([{ color: 'green' }, { status: 'ok' }]);
  *
@@ -496,7 +496,7 @@ Query.prototype._validateOp = function() {
 /**
  * Specifies arguments for a `$and` condition.
  *
- * #### Example
+ * #### Example:
  *
  *     query.and([{ color: 'green' }, { status: 'ok' }])
  *
@@ -514,7 +514,7 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * #### Example
+ * #### Example:
  *
  *     Thing.find().where('age').gt(21);
  *
@@ -639,7 +639,7 @@ Query.prototype._validateOp = function() {
  *
  * When called with one argument, the most recent path passed to `where()` is used.
  *
- * #### Example
+ * #### Example:
  *
  *     const docs = await MyModel.where('tags').size(0).exec();
  *     assert(Array.isArray(docs));
@@ -686,7 +686,7 @@ Query.prototype._validateOp = function() {
  * Specifies a `$mod` condition, filters documents for documents whose
  * `path` property is a number that is equal to `remainder` modulo `divisor`.
  *
- * #### Example
+ * #### Example:
  *
  *     // All find products whose inventory is odd
  *     Product.find().mod('inventory', [2, 1]);
@@ -732,7 +732,7 @@ Query.prototype.mod = function() {
 /**
  * Specifies an `$exists` condition
  *
- * #### Example
+ * #### Example:
  *
  *     // { name: { $exists: true }}
  *     Thing.where('name').exists()
@@ -756,7 +756,7 @@ Query.prototype.mod = function() {
 /**
  * Specifies an `$elemMatch` condition
  *
- * #### Example
+ * #### Example:
  *
  *     query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})
  *
@@ -785,7 +785,7 @@ Query.prototype.mod = function() {
 /**
  * Defines a `$within` or `$geoWithin` argument for geo-spatial queries.
  *
- * #### Example
+ * #### Example:
  *
  *     query.where(path).within().box()
  *     query.where(path).within().circle()
@@ -824,11 +824,11 @@ Query.prototype.mod = function() {
 /**
  * Specifies the maximum number of documents the query will return.
  *
- * #### Example
+ * #### Example:
  *
  *     query.limit(20);
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -857,11 +857,11 @@ Query.prototype.limit = function limit(v) {
 /**
  * Specifies the number of documents to skip.
  *
- * #### Example
+ * #### Example:
  *
  *     query.skip(100).limit(20);
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -891,11 +891,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the maxScan option.
  *
- * #### Example
+ * #### Example:
  *
  *     query.maxScan(100);
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -910,11 +910,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the batchSize option.
  *
- * #### Example
+ * #### Example:
  *
  *     query.batchSize(100)
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -929,11 +929,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies the `comment` option.
  *
- * #### Example
+ * #### Example:
  *
  *     query.comment('login query')
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -948,13 +948,13 @@ Query.prototype.skip = function skip(v) {
 /**
  * Specifies this query as a `snapshot` query.
  *
- * #### Example
+ * #### Example:
  *
  *     query.snapshot(); // true
  *     query.snapshot(true);
  *     query.snapshot(false);
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -969,11 +969,11 @@ Query.prototype.skip = function skip(v) {
 /**
  * Sets query hints.
  *
- * #### Example
+ * #### Example:
  *
  *     query.hint({ indexA: 1, indexB: -1 });
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -1036,7 +1036,7 @@ Query.prototype.projection = function(arg) {
  * either list the fields to include (which excludes all others), or list the fields
  * to exclude (which implies all other fields are included). The [`_id` field is the only exception because MongoDB includes it by default](https://docs.mongodb.com/manual/tutorial/project-fields-from-query-results/#suppress-id-field).
  *
- * #### Example
+ * #### Example:
  *
  *     // include a and b, exclude other fields
  *     query.select('a b');
@@ -1069,7 +1069,7 @@ Query.prototype.projection = function(arg) {
  * @method select
  * @memberOf Query
  * @instance
- * @param {Object|String|Array<String>} arg
+ * @param {Object|String|String[]} arg
  * @return {Query} this
  * @see SchemaType
  * @api public
@@ -1847,7 +1847,7 @@ Query.prototype.setUpdate = function(val) {
  * @method _fieldsForExec
  * @return {Object}
  * @api private
- * @receiver Query
+ * @memberOf Query
  */
 
 Query.prototype._fieldsForExec = function() {
@@ -1859,8 +1859,9 @@ Query.prototype._fieldsForExec = function() {
  * Return an update document with corrected `$set` operations.
  *
  * @method _updateForExec
+ * @return {Object}
  * @api private
- * @receiver Query
+ * @memberOf Query
  */
 
 Query.prototype._updateForExec = function() {
@@ -1907,10 +1908,12 @@ Query.prototype._updateForExec = function() {
 /**
  * Makes sure _path is set.
  *
+ * This method is inherited by `mquery`
+ *
  * @method _ensurePath
  * @param {String} method
  * @api private
- * @receiver Query
+ * @memberOf Query
  */
 
 /**
@@ -2291,7 +2294,7 @@ Query.prototype._find = wrapThunk(function(callback) {
  * If there are too many documents in the result to fit in memory, use
  * [`Query.prototype.cursor()`](api.html#query_Query-cursor)
  *
- * #### Example
+ * #### Example:
  *
  *     // Using async/await
  *     const arr = await Movie.find({ year: { $gte: 1980, $lte: 1989 } });
@@ -2506,7 +2509,7 @@ Query.prototype._findOne = wrapThunk(function(callback) {
  *
  * - `findOne()`
  *
- * #### Example
+ * #### Example:
  *
  *     const query  = Kitten.where({ color: 'white' });
  *     query.findOne(function (err, kitten) {
@@ -2857,7 +2860,7 @@ Query.prototype.__distinct = wrapThunk(function __distinct(callback) {
  *
  * This function does not trigger any middleware.
  *
- * #### Example
+ * #### Example:
  *
  *     distinct(field, conditions, callback)
  *     distinct(field, conditions)
@@ -2918,7 +2921,7 @@ Query.prototype.distinct = function(field, conditions, callback) {
  * sort order of each path is ascending unless the path name is prefixed with `-`
  * which will be treated as descending.
  *
- * #### Example
+ * #### Example:
  *
  *     // sort by "field" ascending and "test" descending
  *     query.sort({ field: 'asc', test: -1 });
@@ -2926,7 +2929,7 @@ Query.prototype.distinct = function(field, conditions, callback) {
  *     // equivalent
  *     query.sort('field -test');
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -2951,7 +2954,7 @@ Query.prototype.sort = function(arg) {
  *
  * This function does not trigger any middleware
  *
- * #### Example
+ * #### Example:
  *
  *     Character.remove({ name: /Stark/ }, callback);
  *
@@ -2963,13 +2966,13 @@ Query.prototype.sort = function(arg) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * #### Example
+ * #### Example:
  *
  *     const res = await Character.remove({ name: /Stark/ });
  *     // Number of docs deleted
  *     res.deletedCount;
  *
- * #### Note
+ * #### Note:
  *
  * Calling `remove()` creates a [Mongoose query](./queries.html), and a query
  * does not execute until you either pass a callback, call [`Query#then()`](#query_Query-then),
@@ -3043,7 +3046,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
  *
  * This function triggers `deleteOne` middleware.
  *
- * #### Example
+ * #### Example:
  *
  *     await Character.deleteOne({ name: 'Eddard Stark' });
  *
@@ -3058,7 +3061,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * #### Example
+ * #### Example:
  *
  *     const res = await Character.deleteOne({ name: 'Eddard Stark' });
  *     // `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }`
@@ -3129,7 +3132,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  *
  * This function triggers `deleteMany` middleware.
  *
- * #### Example
+ * #### Example:
  *
  *     await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
  *
@@ -3144,7 +3147,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  * - `deletedCount`: the number of documents deleted
  * - `n`: the number of documents deleted. Equal to `deletedCount`.
  *
- * #### Example
+ * #### Example:
  *
  *     const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
  *     // `0` if no docs matched the filter, number of docs deleted otherwise
@@ -3296,7 +3299,7 @@ function prepareDiscriminatorCriteria(query) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples
+ * #### Examples:
  *
  *     query.findOneAndUpdate(conditions, update, options, callback) // executes
  *     query.findOneAndUpdate(conditions, update, options)  // returns Query
@@ -3438,7 +3441,7 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples
+ * #### Examples:
  *
  *     A.where().findOneAndRemove(conditions, options, callback) // executes
  *     A.where().findOneAndRemove(conditions, options)  // return Query
@@ -3525,7 +3528,7 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples
+ * #### Examples:
  *
  *     A.where().findOneAndDelete(conditions, options, callback) // executes
  *     A.where().findOneAndDelete(conditions, options)  // return Query
@@ -3644,7 +3647,7 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) {
  *       // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  *     }
  *
- * #### Examples
+ * #### Examples:
  *
  *     A.where().findOneAndReplace(filter, replacement, options, callback); // executes
  *     A.where().findOneAndReplace(filter, replacement, options); // return Query
@@ -3865,7 +3868,7 @@ function _getOption(query, option, def) {
 /*!
  * Override mquery.prototype._findAndModify to provide casting etc.
  *
- * @param {String} type - either "remove" or "update"
+ * @param {String} type either "remove" or "update"
  * @param {Function} callback
  * @api private
  */
@@ -4016,7 +4019,9 @@ Query.prototype._findAndModify = function(type, callback) {
  */
 
 function _completeOneLean(schema, doc, path, res, opts, callback) {
-  if (opts.lean && opts.lean.transform) {
+  if (opts.lean && typeof opts.lean.transform === 'function') {
+    opts.lean.transform(doc);
+
     for (let i = 0; i < schema.childSchemas.length; i++) {
       const childPath = path ? path + '.' + schema.childSchemas[i].model.path : schema.childSchemas[i].model.path;
       const _schema = schema.childSchemas[i].schema;
@@ -4050,7 +4055,11 @@ function _completeOneLean(schema, doc, path, res, opts, callback) {
  */
 
 function _completeManyLean(schema, docs, path, opts, callback) {
-  if (opts.lean && opts.lean.transform) {
+  if (opts.lean && typeof opts.lean.transform === 'function') {
+    for (const doc of docs) {
+      opts.lean.transform(doc);
+    }
+
     for (let i = 0; i < schema.childSchemas.length; i++) {
       const childPath = path ? path + '.' + schema.childSchemas[i].model.path : schema.childSchemas[i].model.path;
       const _schema = schema.childSchemas[i].schema;
@@ -4285,7 +4294,7 @@ Query.prototype._replaceOne = wrapThunk(function(callback) {
  *
  * - `update()`
  *
- * #### Example
+ * #### Example:
  *
  *     Model.where({ _id: id }).update({ title: 'words' });
  *
@@ -4303,11 +4312,11 @@ Query.prototype._replaceOne = wrapThunk(function(callback) {
  *  - `read`
  *  - `writeConcern`
  *
- * #### Note
+ * #### Note:
  *
  * Passing an empty object `{}` as the doc will result in a no-op. The update operation will be ignored and the callback executed without sending the command to MongoDB.
  *
- * #### Note
+ * #### Note:
  *
  * The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the `exec()` method.
  *
@@ -5038,7 +5047,7 @@ function castQuery(query) {
  * a response for each query has also been returned, the results are passed to
  * the callback.
  *
- * @param {Object|String|Array<String>} path either the path(s) to populate or an object specifying all parameters
+ * @param {Object|String|String[]} path either the path(s) to populate or an object specifying all parameters
  * @param {Object|String} [select] Field selection for the population query
  * @param {Model} [model] The model you wish to use for population. If not specified, populate will look up the model by the name in the Schema's `ref` field.
  * @param {Object} [match] Conditions for the population query
@@ -5164,7 +5173,7 @@ function _getPopulatedPaths(list, arr, prefix) {
 /**
  * Casts this query to the schema of `model`
  *
- * #### Note
+ * #### Note:
  *
  * If `obj` is present, it is cast instead of this query.
  *
@@ -5289,7 +5298,7 @@ Query.prototype._applyPaths = function applyPaths() {
  *
  * The `.cursor()` function triggers pre find hooks, but **not** post find hooks.
  *
- * #### Example
+ * #### Example:
  *
  *     // There are 2 ways to use a cursor. First, as a stream:
  *     Thing.
@@ -5360,7 +5369,7 @@ Query.prototype.maxscan = Query.base.maxScan;
 /**
  * Sets the tailable option (for use with capped collections).
  *
- * #### Example
+ * #### Example:
  *
  *     query.tailable(); // true
  *     query.tailable(true);
@@ -5369,7 +5378,7 @@ Query.prototype.maxscan = Query.base.maxScan;
  *     // Set both `tailable` and `awaitData` options
  *     query.tailable({ awaitData: true });
  *
- * #### Note
+ * #### Note:
  *
  * Cannot be used with `distinct()`
  *
@@ -5410,7 +5419,7 @@ Query.prototype.tailable = function(val, opts) {
 /**
  * Declares an intersects query for `geometry()`.
  *
- * #### Example
+ * #### Example:
  *
  *     query.where('path').intersects().geometry({
  *       type: 'LineString',
@@ -5443,7 +5452,7 @@ Query.prototype.tailable = function(val, opts) {
 /**
  * Specifies a `$geometry` condition
  *
- * #### Example
+ * #### Example:
  *
  *     const polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
  *     query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })
@@ -5485,7 +5494,7 @@ Query.prototype.tailable = function(val, opts) {
  *
  * These operators return documents sorted by distance.
  *
- * #### Example
+ * #### Example:
  *
  *     query.where('loc').near({ center: [10, 10] });
  *     query.where('loc').near({ center: [10, 10], maxDistance: 5 });
@@ -5568,13 +5577,13 @@ Query.prototype.near = function() {
 /**
  * _DEPRECATED_ Specifies a `$nearSphere` condition
  *
- * #### Example
+ * #### Example:
  *
  *     query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });
  *
  * **Deprecated.** Use `query.near()` instead with the `spherical` option set to `true`.
  *
- * #### Example
+ * #### Example:
  *
  *     query.where('loc').near({ center: [10, 10], spherical: true });
  *
@@ -5597,7 +5606,7 @@ Query.prototype.nearSphere = function() {
  * You do not need to call this function explicitly, the JavaScript runtime
  * will call it for you.
  *
- * #### Example
+ * #### Example:
  *
  *     for await (const doc of Model.aggregate([{ $sort: { name: 1 } }])) {
  *       console.log(doc.name);
@@ -5625,7 +5634,7 @@ if (Symbol.asyncIterator != null) {
 /**
  * Specifies a `$polygon` condition
  *
- * #### Example
+ * #### Example:
  *
  *     query.where('loc').within().polygon([10, 20], [13, 25], [7, 15]);
  *     query.polygon('loc', [10, 20], [13, 25], [7, 15]);
@@ -5644,7 +5653,7 @@ if (Symbol.asyncIterator != null) {
 /**
  * Specifies a `$box` condition
  *
- * #### Example
+ * #### Example:
  *
  *     const lowerLeft = [40.73083, -73.99756]
  *     const upperRight= [40.741404,  -73.988135]
@@ -5658,8 +5667,8 @@ if (Symbol.asyncIterator != null) {
  * @see $box https://docs.mongodb.org/manual/reference/operator/box/
  * @see within() Query#within #query_Query-within
  * @see https://www.mongodb.org/display/DOCS/Geospatial+Indexing
- * @param {Object} val
- * @param [Array] Upper Right Coords
+ * @param {Object|Array<Number>} val1 Lower Left Coordinates OR a object of lower-left(ll) and upper-right(ur) Coordinates
+ * @param {Array<Number>} [val2] Upper Right Coordinates
  * @return {Query} this
  * @api public
  */
@@ -5681,7 +5690,7 @@ Query.prototype.box = function(ll, ur) {
 /**
  * Specifies a `$center` or `$centerSphere` condition.
  *
- * #### Example
+ * #### Example:
  *
  *     const area = { center: [50, 50], radius: 10, unique: true }
  *     query.where('loc').within().circle(area)
@@ -5726,7 +5735,7 @@ Query.prototype.center = Query.base.circle;
  *
  * **Deprecated.** Use [circle](#query_Query-circle) instead.
  *
- * #### Example
+ * #### Example:
  *
  *     const area = { center: [50, 50], radius: 10 };
  *     query.where('loc').within().centerSphere(area);

package/lib/schema/SubdocumentPath.js

@@ -314,24 +314,28 @@ SubdocumentPath.prototype.discriminator = function(name, schema, options) {
   return this.caster.discriminators[name];
 };
 
+/*!
+ * ignore
+ */
+
+SubdocumentPath.defaultOptions = {};
+
 /**
  * Sets a default option for all SubdocumentPath instances.
  *
  * #### Example:
  *
  *     // Make all numbers have option `min` equal to 0.
- *     mongoose.Schema.Embedded.set('required', true);
+ *     mongoose.Schema.SubdocumentPath.set('required', true);
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
- * @return {undefined}
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
+ * @return {void}
  * @function set
  * @static
  * @api public
  */
 
-SubdocumentPath.defaultOptions = {};
-
 SubdocumentPath.set = SchemaType.set;
 
 /*!

package/lib/schema/array.js

@@ -138,7 +138,7 @@ SchemaArray.schemaName = 'Array';
  *
  * - `castNonArrays`: `true` by default. If `false`, Mongoose will throw a CastError when a value isn't an array. If `true`, Mongoose will wrap the provided value in an array before casting.
  *
- * @static options
+ * @static
  * @api public
  */
 
@@ -161,8 +161,8 @@ SchemaArray.defaultOptions = {};
  *     const User = mongoose.model('User', new Schema({ test: Array }));
  *     new User({ }).validateSync().errors.test.message; // Path `test` is required.
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @api public

package/lib/schema/boolean.js

@@ -55,8 +55,8 @@ SchemaBoolean._cast = castBoolean;
  *     const Order = mongoose.model('Order', new Schema({ isPaid: Boolean }));
  *     new Order({ }).isPaid; // false
  *
- * @param {String} option - The option you'd like to set the value for
- * @param {*} value - value for option
+ * @param {String} option The option you'd like to set the value for
+ * @param {Any} value value for option
  * @return {undefined}
  * @function set
  * @static
@@ -156,7 +156,7 @@ SchemaBoolean.prototype.checkRequired = function(value) {
  *     new M({ b: 'affirmative' }).b; // true
  *
  * @property convertToTrue
- * @type Set
+ * @type {Set}
  * @api public
  */
 
@@ -176,7 +176,7 @@ Object.defineProperty(SchemaBoolean, 'convertToTrue', {
  *     new M({ b: 'nay' }).b; // false
  *
  * @property convertToFalse
- * @type Set
+ * @type {Set}
  * @api public
  */
 
@@ -189,7 +189,7 @@ Object.defineProperty(SchemaBoolean, 'convertToFalse', {
  * Casts to boolean
  *
  * @param {Object} value
- * @param {Object} model - this value is optional
+ * @param {Object} model this value is optional
  * @api private
  */