From 704a5a4d4c395cda6081e7b37905f168ff665632 Mon Sep 17 00:00:00 2001 From: Valeri Karpov Date: Mon, 4 Feb 2019 18:48:21 -0500 Subject: [PATCH] docs: remove confusing references to executing a query immediately Fix #7461 --- docs/queries.jade | 6 +++--- lib/model.js | 23 +++++++++++------------ lib/query.js | 13 +++++++++---- 3 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/queries.jade b/docs/queries.jade index 84626a8be93..4720de3b508 100644 --- a/docs/queries.jade +++ b/docs/queries.jade @@ -39,8 +39,8 @@ block content - [`Model.updateOne()`](/docs/api.html#model_Model.updateOne) A mongoose query can be executed in one of two ways. First, if you - pass in a `callback` function the operation will be executed immediately - with the results passed to the callback. + pass in a `callback` function, Mongoose will execute the query asynchronously + and pass the results to the `callback`. A query also has a `.then()` function, and thus can be used as a promise. @@ -68,7 +68,7 @@ block content }); ``` - Here we see that the query was executed immediately and the results passed to our callback. All callbacks in Mongoose use the pattern: + Mongoose executed the query and passed the results passed to `callback`. All callbacks in Mongoose use the pattern: `callback(error, result)`. If an error occurs executing the query, the `error` parameter will contain an error document, and `result` will be null. If the query is successful, the `error` parameter will be null, and the `result` will be populated with the results of the query. diff --git a/lib/model.js b/lib/model.js index c490408860e..7cb6370e701 100644 --- a/lib/model.js +++ b/lib/model.js @@ -1742,16 +1742,16 @@ Model.deleteMany = function deleteMany(conditions, options, callback) { * // named john and at least 18 * MyModel.find({ name: 'john', age: { $gte: 18 }}); * - * // executes immediately, passing results to callback + * // executes, passing results to callback * MyModel.find({ name: 'john', age: { $gte: 18 }}, function (err, docs) {}); * - * // name LIKE john and only selecting the "name" and "friends" fields, executing immediately + * // executes, name LIKE john and only selecting the "name" and "friends" fields * MyModel.find({ name: /john/i }, 'name friends', function (err, docs) { }) * * // passing options * MyModel.find({ name: /john/i }, null, { skip: 10 }) * - * // passing options and executing immediately + * // passing options and executes * MyModel.find({ name: /john/i }, null, { skip: 10 }, function (err, docs) {}); * * // executing a query explicitly @@ -1824,7 +1824,7 @@ Model.find = function find(conditions, projection, options, callback) { * * ####Example: * - * // find adventure by id and execute immediately + * // find adventure by id and execute * Adventure.findById(id, function (err, adventure) {}); * * // same as above @@ -2050,7 +2050,7 @@ Model.count = function count(conditions, callback) { /** * Creates a Query for a `distinct` operation. * - * Passing a `callback` immediately executes the query. + * Passing a `callback` executes the query. * * ####Example * @@ -2140,7 +2140,7 @@ Model.$where = function $where() { /** * Issues a mongodb findAndModify update command. * - * Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found document (if any) to the callback. The query executes immediately if `callback` is passed else a Query object is returned. + * Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found document (if any) to the callback. The query executes if `callback` is passed else a Query object is returned. * * ####Options: * @@ -2273,8 +2273,7 @@ function _decorateUpdateWithVersionKey(update, options, versionKey) { * * Finds a matching document, updates it according to the `update` arg, * passing any `options`, and returns the found document (if any) to the - * callback. The query executes immediately if `callback` is passed else a - * Query object is returned. + * callback. The query executes if `callback` is passed. * * This function triggers the following middleware. * @@ -2372,7 +2371,7 @@ Model.findByIdAndUpdate = function(id, update, options, callback) { * Finds a matching document, removes it, and passes the found document * (if any) to the callback. * - * Executes immediately if `callback` is passed else a Query object is returned. + * Executes the query if `callback` is passed. * * This function triggers the following middleware. * @@ -2493,7 +2492,7 @@ Model.findByIdAndDelete = function(id, options, callback) { * Finds a matching document, replaces it with the provided doc, and passes the * returned doc to the callback. * - * Executes immediately if `callback` is passed else a Query object is returned. + * Executes the query if `callback` is passed. * * This function triggers the following query middleware. * @@ -2562,7 +2561,7 @@ Model.findOneAndReplace = function(conditions, options, callback) { * * Finds a matching document, removes it, passing the found document (if any) to the callback. * - * Executes immediately if `callback` is passed else a Query object is returned. + * Executes the query if `callback` is passed. * * This function triggers the following middleware. * @@ -2645,7 +2644,7 @@ Model.findOneAndRemove = function(conditions, options, callback) { * * Finds a matching document, removes it, passing the found document (if any) to the callback. * - * Executes immediately if `callback` is passed, else a `Query` object is returned. + * Executes the query if `callback` is passed. * * This function triggers the following middleware. * diff --git a/lib/query.js b/lib/query.js index 62f9c5f9f04..c99bde6ec62 100644 --- a/lib/query.js +++ b/lib/query.js @@ -2702,7 +2702,9 @@ function prepareDiscriminatorCriteria(query) { /** * Issues a mongodb [findAndModify](http://www.mongodb.org/display/DOCS/findAndModify+Command) update command. * - * Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found document (if any) to the callback. The query executes immediately if `callback` is passed. + * Finds a matching document, updates it according to the `update` arg, passing any `options`, and returns the found + * document (if any) to the callback. The query executes if + * `callback` is passed. * * This function triggers the following middleware. * @@ -2833,7 +2835,8 @@ Query.prototype._findOneAndUpdate = wrapThunk(function(callback) { /** * Issues a mongodb [findAndModify](http://www.mongodb.org/display/DOCS/findAndModify+Command) remove command. * - * Finds a matching document, removes it, passing the found document (if any) to the callback. Executes immediately if `callback` is passed. + * Finds a matching document, removes it, passing the found document (if any) to + * the callback. Executes if `callback` is passed. * * This function triggers the following middleware. * @@ -2911,7 +2914,8 @@ Query.prototype.findOneAndRemove = function(conditions, options, callback) { /** * Issues a MongoDB [findOneAndDelete](https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndDelete/) command. * - * Finds a matching document, removes it, and passes the found document (if any) to the callback. Executes immediately if `callback` is passed. + * Finds a matching document, removes it, and passes the found document (if any) + * to the callback. Executes if `callback` is passed. * * This function triggers the following middleware. * @@ -3033,7 +3037,8 @@ Query.prototype._findOneAndDelete = wrapThunk(function(callback) { /** * Issues a MongoDB [findOneAndReplace](https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/) command. * - * Finds a matching document, removes it, and passes the found document (if any) to the callback. Executes immediately if `callback` is passed. + * Finds a matching document, removes it, and passes the found document (if any) + * to the callback. Executes if `callback` is passed. * * This function triggers the following middleware. *