feat: add skipMiddlewareFunction() and overwriteMiddlewareResult() for skipping and modifying middleware results

[vkarpov15]

Fix #11426
Fix #8393

Summary

Right now there's no way to overwrite the result of a function in a post() hook. For example, there's no way to use filter() to modify a find() result in a post('find') hook.

There's also no way to "cancel" an operation in a pre hook without throwing an error. Which is inconvenient, because there are some use cases where it would be great to skip executing the underlying function (local caching, memorizing results, etc.)

This PR adds overwriteMiddlewareResult() for the former, and skipMiddlewareFunction() for the latter, from mongoosejs/kareem#30 .

@AbdelrahmanHafez @Uzlopak what do you think about the naming and overall idea?

Examples

See tests

[Uzlopak]

I think skipMiddleware is better than skipMiddlewareFunction
But it raises the question: are you skipping the middleware or are you skipping the hook? skipMiddleware would tell me that all the potential following hooked functions are also skipped. skipHook would indicate that only this function gets skipped.

So it would be imho good to show in a unit test what happens with following hooks. Are they also skipped or not.

[Uzlopak]

When reading this again, it makes more sense to me, that the all following hooks will get skipped. Right?
Still a unit test were multiple hooks are set should be added.

[vkarpov15]

@Uzlopak following hooks will not be skipped. The purpose of these two functions is to run the entire middleware stack with a modified result. skipMiddlewareFunction() is for use cases where you want to skip the wrapped function but execute the rest of pre and post middleware with a precomputed result (think caching). overwriteMiddlewareResult() is for cases where you want to execute the rest of post middleware with a different result - think using filter() / map() for modifying results and making findOne() return null if the returned result is somehow invalid in a way that you can only compute in JS.

[junmiu]

@vkarpov15 skipMiddlewareFunction only works for Query not QueryCursor, here is an example

// setup a pre hook for find
schema.pre('find', function (next) {
  next(skipMiddlewareFunction([]));
});

// err is { "args": [[]] }, an instance of skipWrappedFunction
mongooseModel.find().cursor().on('error', function (err) { console.log(err); });

The reason is in lib/cursor/QueryCursor.js, it called like this

// here may want to call query._find()
// or wrap this with kareem.createWrapper()
model.hooks.execPre('find', query, (err) => {
  if (err != null) {
    _this._markError(err);
    _this.listeners('error').length > 0 && _this.emit('error', err);
    return;
  }
  // do other things
});