docs(query): document what the resolved value for deleteOne(), `del…

…eteMany()`, and `remove()` contains

Fix #7324

lib/query.js

@@ -2402,39 +2402,52 @@ Query.prototype.sort = function(arg) {
 };
 
 /**
- * Declare and/or execute this query as a remove() operation.
+ * Declare and/or execute this query as a remove() operation. `remove()` is
+ * deprecated, you should use [`deleteOne()`](#query_Query-deleteOne)
+ * or [`deleteMany()`](#query_Query-deleteMany) instead.
  *
  * This function does not trigger any middleware
  *
  * ####Example
  *
- *     Model.remove({ artist: 'Anne Murray' }, callback)
+ *     Character.remove({ name: /Stark/ }, callback);
+ *
+ * This function calls the MongoDB driver's [`Collection#remove()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#remove).
+ * The returned [promise](https://mongoosejs.com/docs/queries.html) resolves to an
+ * object that contains 3 properties:
+ *
+ * - `ok`: `1` if no errors occurred
+ * - `deletedCount`: the number of documents deleted
+ * - `n`: the number of documents deleted. Equal to `deletedCount`.
+ *
+ * ####Example
+ *
+ *     const res = await Character.remove({ name: /Stark/ });
+ *     // Number of docs deleted
+ *     res.deletedCount;
  *
  * ####Note
  *
- * The operation is only executed when a callback is passed. To force execution without a callback, you must first call `remove()` and then execute it by using the `exec()` method.
+ * 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),
+ * or call [`Query#exec()`](#query_Query-exec).
  *
  *     // not executed
- *     var query = Model.find().remove({ name: 'Anne Murray' })
+ *     const query = Character.remove({ name: /Stark/ });
  *
  *     // executed
- *     query.remove({ name: 'Anne Murray' }, callback)
- *     query.remove({ name: 'Anne Murray' }).remove(callback)
+ *     Character.remove({ name: /Stark/ }, callback);
+ *     Character.remove({ name: /Stark/ }).remove(callback);
  *
  *     // executed without a callback
- *     query.exec()
- *
- *     // summary
- *     query.remove(conds, fn); // executes
- *     query.remove(conds)
- *     query.remove(fn) // executes
- *     query.remove()
+ *     Character.exec();
  *
  * @param {Object|Query} [filter] mongodb selector
- * @param {Function} [callback] optional params are (error, writeOpResult)
+ * @param {Function} [callback] optional params are (error, mongooseDeleteResult)
  * @return {Query} this
- * @see writeOpResult http://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~WriteOpResult
- * @see remove http://docs.mongodb.org/manual/reference/method/db.collection.remove/
+ * @deprecated
+ * @see deleteWriteOpResult http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#~deleteWriteOpResult
+ * @see MongoDB driver remove http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#remove
  * @api public
  */
 
@@ -2476,7 +2489,7 @@ Query.prototype._remove = wrapThunk(function(callback) {
 
   callback = _wrapThunkCallback(this, callback);
 
-  return Query.base.remove.call(this, helpers.handleWriteOpResult(callback));
+  return Query.base.remove.call(this, helpers.handleDeleteWriteOpResult(callback));
 });
 
 /**
@@ -2488,14 +2501,28 @@ Query.prototype._remove = wrapThunk(function(callback) {
  *
  * ####Example
  *
- *     Character.deleteOne({ name: 'Eddard Stark' }, callback)
- *     Character.deleteOne({ name: 'Eddard Stark' }).then(next)
+ *     Character.deleteOne({ name: 'Eddard Stark' }, callback);
+ *     Character.deleteOne({ name: 'Eddard Stark' }).then(next);
+ *
+ * This function calls the MongoDB driver's [`Collection#deleteOne()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#deleteOne).
+ * The returned [promise](https://mongoosejs.com/docs/queries.html) resolves to an
+ * object that contains 3 properties:
+ *
+ * - `ok`: `1` if no errors occurred
+ * - `deletedCount`: the number of documents deleted
+ * - `n`: the number of documents deleted. Equal to `deletedCount`.
+ *
+ * ####Example
+ *
+ *     const res = await Character.deleteOne({ name: 'Eddard Stark' });
+ *     // `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }`
+ *     res.deletedCount;
  *
  * @param {Object|Query} [filter] mongodb selector
- * @param {Function} [callback] optional params are (error, writeOpResult)
+ * @param {Function} [callback] optional params are (error, mongooseDeleteResult)
  * @return {Query} this
- * @see writeOpResult http://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~WriteOpResult
- * @see remove http://docs.mongodb.org/manual/reference/method/db.collection.remove/
+ * @see deleteWriteOpResult http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#~deleteWriteOpResult
+ * @see MongoDB Driver deleteOne http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#deleteOne
  * @api public
  */
 
@@ -2538,7 +2565,7 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
 
   callback = _wrapThunkCallback(this, callback);
 
-  return Query.base.deleteOne.call(this, helpers.handleWriteOpResult(callback));
+  return Query.base.deleteOne.call(this, helpers.handleDeleteWriteOpResult(callback));
 });
 
 /**
@@ -2553,11 +2580,25 @@ Query.prototype._deleteOne = wrapThunk(function(callback) {
  *     Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }, callback)
  *     Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }).then(next)
  *
+ * This function calls the MongoDB driver's [`Collection#deleteOne()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#deleteMany).
+ * The returned [promise](https://mongoosejs.com/docs/queries.html) resolves to an
+ * object that contains 3 properties:
+ *
+ * - `ok`: `1` if no errors occurred
+ * - `deletedCount`: the number of documents deleted
+ * - `n`: the number of documents deleted. Equal to `deletedCount`.
+ *
+ * ####Example
+ *
+ *     const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
+ *     // `0` if no docs matched the filter, number of docs deleted otherwise
+ *     res.deletedCount;
+ *
  * @param {Object|Query} [filter] mongodb selector
- * @param {Function} [callback] optional params are (error, writeOpResult)
+ * @param {Function} [callback] optional params are (error, mongooseDeleteResult)
  * @return {Query} this
- * @see writeOpResult http://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#~WriteOpResult
- * @see remove http://docs.mongodb.org/manual/reference/method/db.collection.remove/
+ * @see deleteWriteOpResult http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#~deleteWriteOpResult
+ * @see MongoDB Driver deleteMany http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#deleteMany
  * @api public
  */
 
@@ -2600,7 +2641,7 @@ Query.prototype._deleteMany = wrapThunk(function(callback) {
 
   callback = _wrapThunkCallback(this, callback);
 
-  return Query.base.deleteMany.call(this, helpers.handleWriteOpResult(callback));
+  return Query.base.deleteMany.call(this, helpers.handleDeleteWriteOpResult(callback));
 });
 
 /*!

lib/queryhelpers.js

@@ -296,11 +296,12 @@ function makeLean(val) {
  * Handle the `WriteOpResult` from the server
  */
 
-exports.handleWriteOpResult = function handleWriteOpResult(callback) {
-  return function _handleWriteOpResult(error, res) {
+exports.handleDeleteWriteOpResult = function handleDeleteWriteOpResult(callback) {
+  return function _handleDeleteWriteOpResult(error, res) {
     if (error) {
       return callback(error);
     }
-    return callback(null, res.result);
+    return callback(null,
+      Object.assign({}, res.result, {deletedCount: res.deletedCount }));
   };
 };

test/query.middleware.test.js

@@ -390,7 +390,8 @@ describe('query middleware', function() {
       const Model = db.model('gh7195_deleteOne', schema);
       yield Model.create([{ title: 'foo' }, { title: 'bar' }]);
 
-      yield Model.deleteOne();
+      const res = yield Model.deleteOne();
+      assert.equal(res.deletedCount, 1);
 
       assert.equal(preCount, 1);
       assert.equal(postCount, 1);