lack of documentation of middleware callback

[adelbke]

Prerequisites

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

Issue

Middleware callback functions can have varying parameters; sometimes, pre-hooks have different structures than post-hooks, and query middleware is different than document middleware Yet the structure of the callback lacks clear documentation. I humbly believe it needs to be more evident for newcomers and documented.

The only way to notice this is by inspecting the typescript files on my project, which is slow and time-consuming.
I am ready to contribute to making this improvement in the documentation.

[vkarpov15]

What specifically about the middleware callback is confusing? Our middleware docs show examples of using next vs using async functions, which seems to cover most of what I can think of with the middleware callback.

[adelbke]

I'll explain it to you by giving examples of situations I found myself in when working on a task related to this.

Goal:
I am trying to propagate Mongoose schema events to an event-emitter. A one-to-one mapping would be straightforward. Of each event in a given schema to an event name in the event emitter.

Situations:

• Post Hook of save events (a document middleware) fire twice on each save, and in the first instance, when I access the "this" keyword, it is not a proper document instance as this.constructor.modelName is undefined.
• in the post Hook of save events, I expect to pass a function that looks like the following

function (doc, next) { }

This is expected and documented, but there's no indication of what happens when I pass an async function; it seems to be working, but I still have to call next somehow (which is not bad; I would prefer if I could have the choice not to do see and return a promise).

• In Query Middleware, the "pre" function passes everything regarding the query in the this keyword. But Queries are different; sometimes, there can be an update object, a filter Object, or even an Options Object. They are accessible through functions that may or may not be defined depending on the event. If I try to do what I am doing and react to many different events, I would need to do investigative work to determine which type of query this is.

In this case, I think it would be better if the this keyword were more strictly typed to understand what type of object I am manipulating (is this an update or insertMany ? ). If there is already a way for me to type the Query strictly (I believe there is) that I do not understand, then it means it's either hard to find in the documentation or undocumented.
As to my knowledge, the blog post linked in the docs explains clearly that Query is "ambiguous" in middleware and I think that should be updated

• I also noticed something weird in insertMany mentioned in this issue insertMany middleware #11531. The pre and post middleware functions have different orders of parameters.

• In all the other document events, I had to add an if statement checking if this.constructor.modelName is defined because of occasional double event firing like the save case mentioned above.

I hope this was clear; thank you and apologies for the delayed response.

Edit: updated paragraph structure