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

Fix #11426
Fix #8393

Author: vkarpov15

lib/index.js

@@ -8,6 +8,7 @@ require('./driver').set(require('./drivers/node-mongodb-native'));
 
 const Document = require('./document');
 const EventEmitter = require('events').EventEmitter;
+const Kareem = require('kareem');
 const Schema = require('./schema');
 const SchemaType = require('./schematype');
 const SchemaTypes = require('./schema/index');
@@ -1185,6 +1186,43 @@ Mongoose.prototype._promiseOrCallback = function(callback, fn, ee) {
   return promiseOrCallback(callback, fn, ee, this.Promise);
 };
 
+/**
+ * Use this function in `pre()` middleware to skip calling the wrapped function.
+ *
+ * ####Example:
+ *
+ *     schema.pre('save', function() {
+ *       // Will skip executing `save()`, but will execute post hooks as if
+ *       // `save()` had executed with the result `{ matchedCount: 0 }`
+ *       return mongoose.skipMiddlewareFunction({ matchedCount: 0 });
+ *     });
+ *
+ * @method skipMiddlewareFunction
+ * @param {any} result
+ * @api public
+ */
+
+Mongoose.prototype.skipMiddlewareFunction = Kareem.skipWrappedFunction;
+
+/**
+ * Use this function in `post()` middleware to replace the result
+ *
+ * ####Example:
+ *
+ *     schema.post('find', function(res) {
+ *       // Normally you have to modify `res` in place. But with
+ *       // `overwriteMiddlewarResult()`, you can make `find()` return a
+ *       // completely different value.
+ *       return mongoose.overwriteMiddlewareResult(res.filter(doc => !doc.isDeleted));
+ *     });
+ *
+ * @method overwriteMiddlewareResult
+ * @param {any} result
+ * @api public
+ */
+
+Mongoose.prototype.overwriteMiddlewareResult = Kareem.overwriteResult;
+
 /*!
  * The exports object is an instance of Mongoose.
  *

package.json

@@ -20,7 +20,7 @@
   "license": "MIT",
   "dependencies": {
     "bson": "^4.6.2",
-    "kareem": "2.3.5",
+    "kareem": "2.4.0",
     "mongodb": "4.7.0",
     "mpath": "0.9.0",
     "mquery": "4.0.3",

test/query.middleware.test.js

@@ -636,7 +636,6 @@ describe('query middleware', function() {
     });
     const Model = db.model('Test', schema);
 
-
     await Model.find();
     assert.equal(called, 1);
 
@@ -655,4 +654,38 @@ describe('query middleware', function() {
     await Model.aggregate([{ $match: { name: 'test' } }]);
     assert.equal(called, 3);
   });
+
+  it('allows skipping the wrapped function with `skipMiddlewareFunction()` (gh-11426)', async function() {
+    const schema = Schema({ name: String });
+
+    schema.pre('updateOne', function(next) {
+      next(mongoose.skipMiddlewareFunction({ answer: 42 }));
+    });
+    const Test = db.model('Test', schema);
+
+    const { _id } = await Test.create({ name: 'test' });
+    const res = await Test.updateOne({ _id }, { name: 'changed' });
+    assert.equal(res.answer, 42);
+    assert.strictEqual(res.modifiedCount, undefined);
+
+    const doc = await Test.findById(_id);
+    assert.equal(doc.name, 'test');
+  });
+
+  it('allows overwriting result with `overwriteMiddlewareResult()` (gh-11426)', async function() {
+    const schema = Schema({ name: String });
+
+    schema.post('updateOne', function() {
+      return mongoose.overwriteMiddlewareResult({ answer: 42 });
+    });
+    const Test = db.model('Test', schema);
+
+    const { _id } = await Test.create({ name: 'test' });
+    const res = await Test.updateOne({ _id }, { name: 'changed' });
+    assert.equal(res.answer, 42);
+    assert.strictEqual(res.modifiedCount, undefined);
+
+    const doc = await Test.findById(_id);
+    assert.equal(doc.name, 'changed');
+  });
 });