diff --git a/lib/connection.js b/lib/connection.js index 85f148fcaa..dbb10b1ef7 100644 --- a/lib/connection.js +++ b/lib/connection.js @@ -663,7 +663,7 @@ Connection.prototype.withSession = async function withSession(executor) { * * const session = await conn.startSession(); * let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session }); - * await doc.remove(); + * await doc.deleteOne(); * // `doc` will always be null, even if reading from a replica set * // secondary. Without causal consistency, it is possible to * // get a doc back from the below query if the query reads from a diff --git a/lib/document.js b/lib/document.js index dcf669fdfd..14a33ef323 100644 --- a/lib/document.js +++ b/lib/document.js @@ -2357,17 +2357,17 @@ Document.prototype.$isDefault = function(path) { }; /** - * Getter/setter, determines whether the document was removed or not. + * Getter/setter, determines whether the document was deleted. The `Model.prototype.deleteOne()` method sets `$isDeleted` if the delete operation succeeded. * * #### Example: * - * const product = await product.remove(); + * const product = await product.deleteOne(); * product.$isDeleted(); // true - * product.remove(); // no-op, doesn't send anything to the db + * product.deleteOne(); // no-op, doesn't send anything to the db * * product.$isDeleted(false); * product.$isDeleted(); // false - * product.remove(); // will execute a remove against the db + * product.deleteOne(); // will execute a remove against the db * * * @param {Boolean} [val] optional, overrides whether mongoose thinks the doc is deleted diff --git a/lib/model.js b/lib/model.js index 3ad42386cb..ddf149dd5d 100644 --- a/lib/model.js +++ b/lib/model.js @@ -694,13 +694,20 @@ Model.prototype.$__where = function _where(where) { }; /** - * Delete this document from the db. + * Delete this document from the db. Returns a Query instance containing a `deleteOne` operation by this document's `_id`. * * #### Example: * * await product.deleteOne(); * await Product.findById(product._id); // null * + * Since `deleteOne()` returns a Query, the `deleteOne()` will **not** execute unless you use either `await`, `.then()`, `.catch()`, or [`.exec()`](https://mongoosejs.com/docs/api/query.html#Query.prototype.exec()) + * + * #### Example: + * + * product.deleteOne(); // Doesn't do anything + * product.deleteOne().exec(); // Deletes the document, returns a promise + * * @return {Query} Query * @api public */ @@ -1879,8 +1886,6 @@ Model.translateAliases = function translateAliases(fields, errorOnDuplicates) { /** * Deletes the first document that matches `conditions` from the collection. * It returns an object with the property `deletedCount` indicating how many documents were deleted. - * Behaves like `remove()`, but deletes at most one document regardless of the - * `single` option. * * #### Example: * @@ -1914,8 +1919,6 @@ Model.deleteOne = function deleteOne(conditions, options) { /** * Deletes all of the documents that match `conditions` from the collection. * It returns an object with the property `deletedCount` containing the number of documents deleted. - * Behaves like `remove()`, but deletes all documents that match `conditions` - * regardless of the `single` option. * * #### Example: * @@ -2729,7 +2732,7 @@ Model.create = async function create(doc, options) { * // operationType: 'delete', * // ns: { db: 'mydb', coll: 'Person' }, * // documentKey: { _id: 5a51b125c5500f5aa094c7bd } } - * await doc.remove(); + * await doc.deleteOne(); * * @param {Array} [pipeline] * @param {Object} [options] see the [mongodb driver options](https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#watch) @@ -2777,7 +2780,7 @@ Model.watch = function(pipeline, options) { * * const session = await Person.startSession(); * let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session }); - * await doc.remove(); + * await doc.deleteOne(); * // `doc` will always be null, even if reading from a replica set * // secondary. Without causal consistency, it is possible to * // get a doc back from the below query if the query reads from a