mongoose 6.4.4 → 6.4.7

package/lib/aggregate.js

@@ -19,7 +19,7 @@ const validRedactStringValues = new Set(['$$DESCEND', '$$PRUNE', '$$KEEP']);
 
 /**
  * Aggregate constructor used for building aggregation pipelines. Do not
- * instantiate this class directly, use [Model.aggregate()](/docs/api.html#model_Model.aggregate) instead.
+ * instantiate this class directly, use [Model.aggregate()](/docs/api.html#model_Model-aggregate) instead.
  *
  * #### Example:
  *
@@ -38,11 +38,9 @@ const validRedactStringValues = new Set(['$$DESCEND', '$$PRUNE', '$$KEEP']);
  * - The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
  * - Mongoose does **not** cast pipeline stages. The below will **not** work unless `_id` is a string in the database
  *
- * ```javascript
- *   new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]);
- *   // Do this instead to cast to an ObjectId
- *   new Aggregate([{ $match: { _id: new mongoose.Types.ObjectId('00000000000000000000000a') } }]);
- * ```
+ *     new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]);
+ *     // Do this instead to cast to an ObjectId
+ *     new Aggregate([{ $match: { _id: new mongoose.Types.ObjectId('00000000000000000000000a') } }]);
  *
  * @see MongoDB https://docs.mongodb.org/manual/applications/aggregation/
  * @see driver https://mongodb.github.com/node-mongodb-native/api-generated/collection.html#aggregate
@@ -72,8 +70,8 @@ function Aggregate(pipeline, model) {
  * - [`cursor`](./api.html#aggregate_Aggregate-cursor)
  * - [`explain`](./api.html#aggregate_Aggregate-explain)
  * - `fieldsAsRaw`
- * - hint
- * - let
+ * - `hint`
+ * - `let`
  * - `maxTimeMS`
  * - `raw`
  * - `readConcern`
@@ -92,6 +90,7 @@ Aggregate.prototype.options;
  * Get/set the model that this aggregation will execute on.
  *
  * #### Example:
+ *
  *     const aggregate = MyModel.aggregate([{ $match: { answer: 42 } }]);
  *     aggregate.model() === MyModel; // true
  *
@@ -99,7 +98,7 @@ Aggregate.prototype.options;
  *     aggregate.model(SomeOtherModel);
  *     aggregate.model() === SomeOtherModel; // true
  *
- * @param {Model} [model] set the model associated with this aggregate.
+ * @param {Model} [model] Set the model associated with this aggregate. If not provided, returns the already stored model.
  * @return {Model}
  * @api public
  */
@@ -135,7 +134,7 @@ Aggregate.prototype.model = function(model) {
  *     const pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
  *     aggregate.append(pipeline);
  *
- * @param {Object} ops operator(s) to append
+ * @param {...Object|Object[]} ops operator(s) to append. Can either be a spread of objects or a single parameter of a object array.
  * @return {Aggregate}
  * @api public
  */
@@ -364,7 +363,7 @@ Aggregate.prototype.near = function(arg) {
  *     aggregate.unwind({ path: '$tags', preserveNullAndEmptyArrays: true });
  *
  * @see $unwind https://docs.mongodb.org/manual/reference/aggregation/unwind/
- * @param {String|Object} fields the field(s) to unwind, either as field names or as [objects with options](https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/#document-operand-with-options). If passing a string, prefixing the field name with '$' is optional. If passing an object, `path` must start with '$'.
+ * @param {String|Object|String[]|Object[]} fields the field(s) to unwind, either as field names or as [objects with options](https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/#document-operand-with-options). If passing a string, prefixing the field name with '$' is optional. If passing an object, `path` must start with '$'.
  * @return {Aggregate}
  * @api public
  */
@@ -495,6 +494,7 @@ Aggregate.prototype.lookup = function(options) {
  * Note that graphLookup can only consume at most 100MB of memory, and does not allow disk use even if `{ allowDiskUse: true }` is specified.
  *
  * #### Examples:
+ *
  *      // Suppose we have a collection of courses, where a document might look like `{ _id: 0, name: 'Calculus', prerequisite: 'Trigonometry'}` and `{ _id: 0, name: 'Trigonometry', prerequisite: 'Algebra' }`
  *      aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites
  *
@@ -602,7 +602,8 @@ Aggregate.prototype.sort = function(arg) {
  *
  * @see $unionWith https://docs.mongodb.com/manual/reference/operator/aggregation/unionWith
  * @param {Object} options to $unionWith query as described in the above link
- * @return {Aggregate}* @api public
+ * @return {Aggregate}
+ * @api public
  */
 
 Aggregate.prototype.unionWith = function(options) {
@@ -617,8 +618,8 @@ Aggregate.prototype.unionWith = function(options) {
  *
  *     await Model.aggregate(pipeline).read('primaryPreferred');
  *
- * @param {String} pref one of the listed preference options or their aliases
- * @param {Array} [tags] optional tags for this query
+ * @param {String|ReadPreference} pref one of the listed preference options or their aliases
+ * @param {Array} [tags] optional tags for this query. DEPRECATED
  * @return {Aggregate} this
  * @api public
  * @see mongodb https://docs.mongodb.org/manual/applications/replication/#read-preference
@@ -703,9 +704,9 @@ Aggregate.prototype.redact = function(expression, thenExpr, elseExpr) {
  *
  *     Model.aggregate(..).explain(callback)
  *
- * @param {String} verbosity
- * @param {Function} callback
- * @return {Promise}
+ * @param {String} [verbosity]
+ * @param {Function} [callback] The callback function to call, if not specified, will return a Promise instead.
+ * @return {Promise} Returns a promise if no "callback" is given
  */
 
 Aggregate.prototype.explain = function(verbosity, callback) {
@@ -772,6 +773,7 @@ Aggregate.prototype.explain = function(verbosity, callback) {
  *     await Model.aggregate([{ $match: { foo: 'bar' } }]).allowDiskUse(true);
  *
  * @param {Boolean} value Should tell server it can use hard drive to store data during aggregation.
+ * @return {Aggregate} this
  * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/
  */
 
@@ -788,6 +790,7 @@ Aggregate.prototype.allowDiskUse = function(value) {
  *     Model.aggregate(..).hint({ qty: 1, category: 1 }).exec(callback)
  *
  * @param {Object|String} value a hint object or the index name
+ * @return {Aggregate} this
  * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/
  */
 
@@ -805,6 +808,7 @@ Aggregate.prototype.hint = function(value) {
  *     await Model.aggregate(..).session(session);
  *
  * @param {ClientSession} session
+ * @return {Aggregate} this
  * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/
  */
 
@@ -826,10 +830,10 @@ Aggregate.prototype.session = function(session) {
  *     agg.options; // `{ allowDiskUse: true }`
  *
  * @param {Object} options keys to merge into current options
- * @param [options.maxTimeMS] number limits the time this aggregation will run, see [MongoDB docs on `maxTimeMS`](https://docs.mongodb.com/manual/reference/operator/meta/maxTimeMS/)
- * @param [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation
- * @param [options.collation] object see [`Aggregate.prototype.collation()`](./docs/api.html#aggregate_Aggregate-collation)
- * @param [options.session] ClientSession see [`Aggregate.prototype.session()`](./docs/api.html#aggregate_Aggregate-session)
+ * @param {Number} [options.maxTimeMS] number limits the time this aggregation will run, see [MongoDB docs on `maxTimeMS`](https://docs.mongodb.com/manual/reference/operator/meta/maxTimeMS/)
+ * @param {Boolean} [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation
+ * @param {Object} [options.collation] object see [`Aggregate.prototype.collation()`](./docs/api.html#aggregate_Aggregate-collation)
+ * @param {ClientSession} [options.session] ClientSession see [`Aggregate.prototype.session()`](./docs/api.html#aggregate_Aggregate-session)
  * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/
  * @return {Aggregate} this
  * @api public
@@ -855,7 +859,7 @@ Aggregate.prototype.option = function(value) {
  *     });
  *
  * @param {Object} options
- * @param {Number} options.batchSize set the cursor batch size
+ * @param {Number} [options.batchSize] set the cursor batch size
  * @param {Boolean} [options.useMongooseAggCursor] use experimental mongoose-specific aggregation cursor (for `eachAsync()` and other query cursor semantics)
  * @return {AggregationCursor} cursor representing this aggregation
  * @api public
@@ -940,11 +944,10 @@ Aggregate.prototype.search = function(options) {
  *
  *     MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }]
  *
- * @return {Array}
+ * @return {Array} The current pipeline similar to the operation that will be executed
  * @api public
  */
 
-
 Aggregate.prototype.pipeline = function() {
   return this._pipeline;
 };
@@ -957,12 +960,10 @@ Aggregate.prototype.pipeline = function() {
  *     aggregate.exec(callback);
  *
  *     // Because a promise is returned, the `callback` is optional.
- *     const promise = aggregate.exec();
- *     promise.then(..);
+ *     const result = await aggregate.exec();
  *
- * @see Promise #promise_Promise
  * @param {Function} [callback]
- * @return {Promise}
+ * @return {Promise} Returns a Promise if no "callback" is given.
  * @api public
  */
 
@@ -1018,13 +1019,13 @@ Aggregate.prototype.exec = function(callback) {
 };
 
 /**
- * Provides promise for aggregate.
+ * Provides a Promise-like `then` function, which will call `.exec` without a callback
+ * Compatible with `await`.
  *
  * #### Example:
  *
  *     Model.aggregate(..).then(successCallback, errorCallback);
  *
- * @see Promise #promise_Promise
  * @param {Function} [resolve] successCallback
  * @param {Function} [reject]  errorCallback
  * @return {Promise}
@@ -1037,6 +1038,7 @@ Aggregate.prototype.then = function(resolve, reject) {
  * Executes the query returning a `Promise` which will be
  * resolved with either the doc(s) or rejected with the error.
  * Like [`.then()`](#query_Query-then), but only takes a rejection handler.
+ * Compatible with `await`.
  *
  * @param {Function} [reject]
  * @return {Promise}

package/lib/browser.js

@@ -103,7 +103,7 @@ exports.VirtualType = require('./virtualtype');
  * _Alias of mongoose.Schema.Types for backwards compatibility._
  *
  * @property SchemaTypes
- * @see Schema.SchemaTypes #schema_Schema.Types
+ * @see Schema.SchemaTypes #schema_Schema-Types
  * @api public
  */
 

package/lib/cast.js

@@ -24,8 +24,8 @@ const ALLOWED_GEOWITHIN_GEOJSON_TYPES = ['Polygon', 'MultiPolygon'];
  *
  * @param {Schema} schema
  * @param {Object} obj Object to cast
- * @param {Object} options the query options
- * @param {Query} context passed to setters
+ * @param {Object} [options] the query options
+ * @param {Query} [context] passed to setters
  * @api private
  */
 module.exports = function cast(schema, obj, options, context) {

package/lib/collection.js

@@ -15,7 +15,7 @@ const immediate = require('./helpers/immediate');
  *
  * @param {String} name name of the collection
  * @param {Connection} conn A MongooseConnection instance
- * @param {Object} opts optional collection options
+ * @param {Object} [opts] optional collection options
  * @api public
  */
 

package/lib/connection.js

@@ -393,7 +393,7 @@ Connection.prototype.config;
  * @param {string} collection The collection to create
  * @param {Object} [options] see [MongoDB driver docs](https://mongodb.github.io/node-mongodb-native/2.2/api/Db.html#createCollection)
  * @param {Function} [callback]
- * @return {Promise}
+ * @return {Promise} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -521,7 +521,7 @@ Connection.prototype.transaction = function transaction(fn, options) {
  * @method dropCollection
  * @param {string} collection The collection to delete
  * @param {Function} [callback]
- * @return {Promise}
+ * @return {Promise} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -541,7 +541,7 @@ Connection.prototype.dropCollection = _wrapConnHelper(function dropCollection(co
  *
  * @method dropDatabase
  * @param {Function} [callback]
- * @return {Promise}
+ * @return {Promise} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -608,6 +608,8 @@ Connection.prototype._shouldBufferCommands = function _shouldBufferCommands() {
  *
  * @param {Error} err
  * @param {Function} callback optional
+ * @emits "error" Emits the `error` event with the given `err`, unless a callback is specified
+ * @returns {Promise|null} Returns a rejected Promise if no `callback` is given.
  * @api private
  */
 
@@ -668,7 +670,7 @@ Connection.prototype.onOpen = function() {
  * @param {Number} [options.family=0] Passed transparently to [Node.js' `dns.lookup()`](https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback) function. May be either `0, `4`, or `6`. `4` means use IPv4 only, `6` means use IPv6 only, `0` means try both.
  * @param {Boolean} [options.autoCreate=false] Set to `true` to make Mongoose automatically call `createCollection()` on every model created on this connection.
  * @param {Function} [callback]
- * @returns {Connection} this
+ * @returns {Promise<Connection>} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -913,6 +915,14 @@ function _setClient(conn, client, options, dbName) {
   }
 }
 
+/**
+ * Destory the connection (not just a alias of [`.close`](#connection_Connection-close))
+ *
+ * @param {Boolean} [force]
+ * @param {Function} [callback]
+ * @returns {Promise} Returns a Promise if no `callback` is given.
+ */
+
 Connection.prototype.destroy = function(force, callback) {
   if (typeof force === 'function') {
     callback = force;
@@ -935,7 +945,7 @@ Connection.prototype.destroy = function(force, callback) {
  *
  * @param {Boolean} [force] optional
  * @param {Function} [callback] optional
- * @return {Promise}
+ * @return {Promise} Returns a Promise if no `callback` is given.
  * @api public
  */
 
@@ -961,7 +971,8 @@ Connection.prototype.close = function(force, callback) {
  *
  * @param {Boolean} force
  * @param {Boolean} destroy
- * @param {Function} callback
+ * @param {Function} [callback]
+ * @returns {Connection} this
  * @api private
  */
 Connection.prototype._close = function(force, destroy, callback) {
@@ -1081,6 +1092,7 @@ Connection.prototype.collection = function(name, options) {
  * Equivalent to calling `.plugin(fn)` on each schema you create.
  *
  * #### Example:
+ *
  *     const db = mongoose.createConnection('mongodb://localhost:27017/mydb');
  *     db.plugin(() => console.log('Applied'));
  *     db.plugins.length; // 1
@@ -1108,7 +1120,7 @@ Connection.prototype.plugin = function(fn, opts) {
  *     const Ticket = db.model('Ticket', new Schema(..));
  *     const Venue = db.model('Venue');
  *
- * _When no `collection` argument is passed, Mongoose produces a collection name by passing the model `name` to the [utils.toCollectionName](#utils_exports.toCollectionName) method. This method pluralizes the name. If you don't like this behavior, either pass a collection name or set your schemas collection name option._
+ * _When no `collection` argument is passed, Mongoose produces a collection name by passing the model `name` to the [utils.toCollectionName](#utils_exports-toCollectionName) method. This method pluralizes the name. If you don't like this behavior, either pass a collection name or set your schemas collection name option._
  *
  * #### Example:
  *
@@ -1274,7 +1286,7 @@ Connection.prototype.deleteModel = function(name) {
 
 /**
  * Watches the entire underlying database for changes. Similar to
- * [`Model.watch()`](/docs/api/model.html#model_Model.watch).
+ * [`Model.watch()`](/docs/api/model.html#model_Model-watch).
  *
  * This function does **not** trigger any middleware. In particular, it
  * does **not** trigger aggregate middleware.
@@ -1330,6 +1342,7 @@ Connection.prototype.watch = function(pipeline, options) {
  * to connect.
  *
  * #### Example:
+ *
  *     const conn = await mongoose.createConnection('mongodb://localhost:27017/test').
  *       asPromise();
  *     conn.readyState; // 1, means Mongoose is connected
@@ -1345,7 +1358,7 @@ Connection.prototype.asPromise = function asPromise() {
 /**
  * Returns an array of model names created on this connection.
  * @api public
- * @return {Array}
+ * @return {String[]}
  */
 
 Connection.prototype.modelNames = function() {
@@ -1353,9 +1366,10 @@ Connection.prototype.modelNames = function() {
 };
 
 /**
- * @brief Returns if the connection requires authentication after it is opened. Generally if a
+ * Returns if the connection requires authentication after it is opened. Generally if a
  * username and password are both provided than authentication is needed, but in some cases a
  * password is not required.
+ *
  * @api private
  * @return {Boolean} true if the connection should be authenticated after it is opened, otherwise false.
  */
@@ -1365,8 +1379,9 @@ Connection.prototype.shouldAuthenticate = function() {
 };
 
 /**
- * @brief Returns a boolean value that specifies if the current authentication mechanism needs a
+ * Returns a boolean value that specifies if the current authentication mechanism needs a
  * password to authenticate according to the auth objects passed into the openUri methods.
+ *
  * @api private
  * @return {Boolean} true if the authentication mechanism specified in the options object requires
  *  a password, otherwise false.
@@ -1379,10 +1394,11 @@ Connection.prototype.authMechanismDoesNotRequirePassword = function() {
 };
 
 /**
- * @brief Returns a boolean value that specifies if the provided objects object provides enough
+ * Returns a boolean value that specifies if the provided objects object provides enough
  * data to authenticate with. Generally this is true if the username and password are both specified
  * but in some authentication methods, a password is not required for authentication so only a username
  * is required.
+ *
  * @param {Object} [options] the options object passed into the openUri methods.
  * @api private
  * @return {Boolean} true if the provided options object provides enough data to authenticate with,
@@ -1399,6 +1415,7 @@ Connection.prototype.optionsProvideAuthenticationData = function(options) {
  * that this connection uses to talk to MongoDB.
  *
  * #### Example:
+ *
  *     const conn = await mongoose.createConnection('mongodb://localhost:27017/test').
  *       asPromise();
  *
@@ -1418,6 +1435,7 @@ Connection.prototype.getClient = function getClient() {
  * reuse it.
  *
  * #### Example:
+ *
  *     const client = await mongodb.MongoClient.connect('mongodb://localhost:27017/test');
  *
  *     const conn = mongoose.createConnection().setClient(client);
@@ -1426,6 +1444,7 @@ Connection.prototype.getClient = function getClient() {
  *     conn.readyState; // 1, means 'CONNECTED'
  *
  * @api public
+ * @param {MongClient} client The Client to set to be used.
  * @return {Connection} this
  */
 
@@ -1447,12 +1466,11 @@ Connection.prototype.setClient = function setClient(client) {
 };
 
 /**
- *
  * Syncs all the indexes for the models registered with this connection.
  *
- * @param {Object} options
- * @param {Boolean} options.continueOnError `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model.
- * @return {Promise} Returns a Promise, when the Promise resolves the value is a list of the dropped indexes.
+ * @param {Object} [options]
+ * @param {Boolean} [options.continueOnError] `false` by default. If set to `true`, mongoose will not throw an error if one model syncing failed, and will return an object where the keys are the names of the models, and the values are the results/errors for each model.
+ * @return {Promise<Object>} Returns a Promise, when the Promise resolves the value is a list of the dropped indexes.
  */
 Connection.prototype.syncIndexes = async function syncIndexes(options = {}) {
   const result = {};