Describe `deleteOne` or `remove` method of Document in the doc

[igoradamenko]

Prerequisites

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

Mongoose version

8.3.2

Node.js version

18.17.0

MongoDB server version

7.0.8

Typescript version (if applicable)

Not using.

Description

Please, note, I'm a new user of Mongoose and may get something wrong 🙂

I was reading the API reference and tripped over the Document.prototype.$isDeleted() example. It has this line:

const product = await product.remove();

Previously I was using Model.deleteOne() to remove an entity, but the use of Document.prototype.remove would be better it my case. So I went and gave it a shot, but it did not work.

I checked sources and did not find any traces of .remove method for Document. So, I checked the types, and found .deleteOne there.

I tried .deleteOne, it worked. But I could not find this method in the doc. So, I'm not quite sure is it safe to use it? Search results do not show any results from e.g. FAQ.

My best guesses are:

1. There are some methods that applied to the Document.prototype as “hooks”. deleteOne is one of them, same as save. They are safe to use.

2. Previously deleteOne was named remove, but was renamed. (According to https://github.com/Automattic/mongoose/issues/13284#issuecomment-1519118631).

3. The example with product.remove is outdated and should be rewritten with .deleteOne.

4. deleteOne should be described in JSDoc like the save method. Without related code, just a JSDoc block for the API reference.

If my guesses are correct, feel free to ping me, I will send a PR. If they are not, please, explain whether it's safe to use deleteOne, or not 🐨

Steps to Reproduce

1. Find any document via Model.findOne.
2. Call .remove on this document, get TypeError: doc.remove is not a function.
3. Call .deleteOne on this document, get no error.
4. Open the Document API reference, Ctrl+F for .remove, find it in an example.
5. Open the Document API reference, Ctrl+F for .deleteOne, find nothing.

Expected Behavior

Document deletion method should be described in the doc properly. If it exists of course.

[IslandRhythms]

remove was removed https://mongoosejs.com/docs/migrating_to_7.html#removed-remove going from 6 => 7

[igoradamenko]

@IslandRhythms, ah, thanks!

I grepped over different versions of the doc for remove, but did not find anything. My bad, I did not look in the migration guides :-)

[igoradamenko]

@vkarpov15, but why is it closed?

I do not see deleteOne described in the doc right now.

Is there a PR, a commit, or something that makes this issue closed?

I offered help here, but did not get the answer though.

[vkarpov15]

It's under Model.prototype.deleteOne() here: https://mongoosejs.com/docs/api/model.html#Model.prototype.deleteOne() . A bit confusing, I know, but the idea is that Document is the base class, and Model extends Document. Document class contains all the sync change tracking logic, Model class contains all the MongoDB operations. What we typically refer to as a "document" in Mongoose is actually an instance of the Model class.