[Docs] Contradiction in docs/middleware.md

[RobbyCBennett]

Prerequisites

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

Issue

Here's the page.

I ran into this issue while trying to use pre/post middleware with Model.save().

According to the top of the doc, save middleware is only supported for the Document class.

However, the section Define Middleware Before Compiling Models shows that save middleware is supported for Model.

The code snippets in the section don't work for me, but save should be a basic supported feature. For example, pre middleware to save a user can encrypt a password.

[RobbyCBennett]

Additionally, the unordered lists in Types of Middleware could have titles for clarity. For example:

Types of Middleware

Mongoose has 4 types of middleware: document middleware, model middleware, aggregate middleware, and query middleware. Document middleware is supported for the following document functions. In document middleware functions, this refers to the document.

Document:

• validate
• save
• remove
• updateOne
• deleteOne
• init (note: init hooks are synchronous)

[vkarpov15]

How exactly does the section you linked to "shows that save middleware is supported for Model"? Document middleware = middleware for documents (which are instances of Models). Model middleware = middleware for static functions on models, like insertMany()

[RobbyCBennett]

I misunderstood the unique terms that mongo uses. The following expression snippet makes a Document, but I thought it was a Model because it is an instance of a Model.

new User({ name: 'test' })

I was confused because "documents represent a one-to-one mapping to documents as stored in MongoDB" so I assumed that a model created, but not yet saved was just a Model instance, but not a Document yet.

[RobbyCBennett]

So I guess there isn't a contradiction in docs/middleware.md, but perhaps the sentence quoted from docs/documents.md could be updated to clarify that documents not a one-to-one mapping to documents as stored in MongoDB, as they can be created and not saved.

[vkarpov15]

That's fair. I think it's worth clarifying a little bit the difference between models and documents in the middleware docs.