Inconsistent documentation on remove/deleteOne

[esaule]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Mongoose version

8.9.0

Node.js version

20.0

MongoDB server version

7.0

Typescript version (if applicable)

No response

Description

The documentation on mongoose is inconsistent since the prototype.remove() has been removed in mongoose 7.x. The migration guide ( https://mongoosejs.com/docs/migrating_to_7.html#removed-remove ) note that remove() has been removed and replaced by deleteOne() and notes for documents:

// For documents, change this:
await doc.remove();

// To this:
await doc.deleteOne();

The Document API ( https://mongoosejs.com/docs/api/document.html ) does not include the deleteOne function. Moreover, the documentation still contains reference to remove(): for instance in the documentation of $isdeleted ( https://mongoosejs.com/docs/api/document.html#Document.prototype.$isDeleted() ) but there are more.

Steps to Reproduce

1. read the migration documentation
2. cry

Expected Behavior

functions referenced in the migration guide are expected to be documented.

In particular, I am running into an issue where a call to Document.deleteOne() is not reflected in the database unless I .then() the query. It is unclear whether this is expected behavior or not. The documentation should clarify.

[vkarpov15]

Re: Document.prototype.deleteOne() not being in the docs, that is because this function is documented as Model.prototype.deleteOne(). Admittedly this is somewhat confusing. The rationale is that Document is the base class that is responsible for change tracking, validation, and all non-MongoDB-related stuff. And Model is a class that extends Document which defines MongoDB operations, like findOne(), save(), etc. We aren't 100% consistent about this distinction because of legacy code and not wanting to break links.

As for documentation referencing remove(), and the documentation not clarifying that you need to either await, .then(), .catch() or .exec() on deleteOne() to execute the delete, those are documentation issues that we should fix.