kareem 2.3.3 → 2.4.0

package/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Test
+on:
+  pull_request:
+  push:
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [12, 14, 16, 18]
+        os: [ubuntu-20.04]
+        include:
+          - os: ubuntu-20.04
+            mongo-os: ubuntu2004
+    name: Node ${{ matrix.node }}
+    steps:
+      - uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # v3
+
+      - name: Setup node
+        uses: actions/setup-node@5b52f097d36d4b0b2f94ed6de710023fbb8b2236 # v3.1.0
+        with:
+          node-version: ${{ matrix.node }}
+
+      - run: npm install
+
+      - run: npm test

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+<a name="2.4.0"></a>
+## 2.4.0 (2022-06-13)
+
+* feat: add `overwriteResult()` and `skipWrappedFunction()` for more advanced control flow
+
+<a name="2.3.4"></a>
+## 2.3.4 (2022-02-10)
+
+* perf: various performance improvements #27 #24 #23 #22 #21 #20
+
 <a name="2.3.3"></a>
 ## 2.3.3 (2021-12-26)
 

package/index.js

@@ -5,21 +5,38 @@ function Kareem() {
   this._posts = new Map();
 }
 
+Kareem.skipWrappedFunction = function skipWrappedFunction() {
+  if (!(this instanceof Kareem.skipWrappedFunction)) {
+    return new Kareem.skipWrappedFunction(...arguments);
+  }
+
+  this.args = [...arguments];
+};
+
+Kareem.overwriteResult = function overwriteResult() {
+  if (!(this instanceof Kareem.overwriteResult)) {
+    return new Kareem.overwriteResult(...arguments);
+  }
+
+  this.args = [...arguments];
+};
+
 Kareem.prototype.execPre = function(name, context, args, callback) {
   if (arguments.length === 3) {
     callback = args;
     args = [];
   }
-  var pres = get(this._pres, name, []);
+  var pres = this._pres.get(name) || [];
   var numPres = pres.length;
   var numAsyncPres = pres.numAsync || 0;
   var currentPre = 0;
   var asyncPresLeft = numAsyncPres;
   var done = false;
   var $args = args;
+  var shouldSkipWrappedFunction = null;
 
   if (!numPres) {
-    return process.nextTick(function() {
+    return nextTick(function() {
       callback(null);
     });
   }
@@ -38,11 +55,15 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
             if (done) {
               return;
             }
-            done = true;
-            return callback(error);
+            if (error instanceof Kareem.skipWrappedFunction) {
+              shouldSkipWrappedFunction = error;
+            } else {
+              done = true;
+              return callback(error);
+            }
           }
           if (--asyncPresLeft === 0 && currentPre >= numPres) {
-            return callback(null);
+            return callback(shouldSkipWrappedFunction);
           }
         })
       ];
@@ -57,25 +78,25 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
 
       callMiddlewareFunction(pre.fn, context, args, args[0]);
     } else {
-      let maybePromise = null;
+      let maybePromiseLike = null;
       try {
-        maybePromise = pre.fn.call(context);
+        maybePromiseLike = pre.fn.call(context);
       } catch (err) {
         if (err != null) {
           return callback(err);
         }
       }
 
-      if (isPromise(maybePromise)) {
-        maybePromise.then(() => _next(), err => _next(err));
+      if (isPromiseLike(maybePromiseLike)) {
+        maybePromiseLike.then(() => _next(), err => _next(err));
       } else {
         if (++currentPre >= numPres) {
           if (asyncPresLeft > 0) {
             // Leave parallel hooks to run
             return;
           } else {
-            return process.nextTick(function() {
-              callback(null);
+            return nextTick(function() {
+              callback(shouldSkipWrappedFunction);
             });
           }
         }
@@ -91,8 +112,12 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
       if (done) {
         return;
       }
-      done = true;
-      return callback(error);
+      if (error instanceof Kareem.skipWrappedFunction) {
+        shouldSkipWrappedFunction = error;
+      } else {
+        done = true;
+        return callback(error);
+      }
     }
 
     if (++currentPre >= numPres) {
@@ -100,7 +125,7 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
         // Leave parallel hooks to run
         return;
       } else {
-        return callback(null);
+        return callback(shouldSkipWrappedFunction);
       }
     }
 
@@ -109,7 +134,7 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
 };
 
 Kareem.prototype.execPreSync = function(name, context, args) {
-  var pres = get(this._pres, name, []);
+  var pres = this._pres.get(name) || [];
   var numPres = pres.length;
 
   for (var i = 0; i < numPres; ++i) {
@@ -122,7 +147,7 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
     callback = options;
     options = null;
   }
-  var posts = get(this._posts, name, []);
+  var posts = this._posts.get(name) || [];
   var numPosts = posts.length;
   var currentPost = 0;
 
@@ -132,7 +157,7 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
   }
 
   if (!numPosts) {
-    return process.nextTick(function() {
+    return nextTick(function() {
       callback.apply(null, [firstError].concat(args));
     });
   }
@@ -151,8 +176,15 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
 
     if (firstError) {
       if (post.length === numArgs + 2) {
-        var _cb = decorateNextFn(function(error) {
+        const _cb = decorateNextFn(function(error) {
           if (error) {
+            if (error instanceof Kareem.overwriteResult) {
+              args = error.args;
+              if (++currentPost >= numPosts) {
+                return callback.call(null, firstError);
+              }
+              return next();
+            }
             firstError = error;
           }
           if (++currentPost >= numPosts) {
@@ -172,6 +204,13 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
     } else {
       const _cb = decorateNextFn(function(error) {
         if (error) {
+          if (error instanceof Kareem.overwriteResult) {
+            args = error.args;
+            if (++currentPost >= numPosts) {
+              return callback.apply(null, [null].concat(args));
+            }
+            return next();
+          }
           firstError = error;
           return next();
         }
@@ -194,23 +233,27 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
         callMiddlewareFunction(post, context, newArgs.concat([_cb]), _cb);
       } else {
         let error;
-        let maybePromise;
+        let maybePromiseLike;
         try {
-          maybePromise = post.apply(context, newArgs);
+          maybePromiseLike = post.apply(context, newArgs);
         } catch (err) {
           error = err;
           firstError = err;
         }
 
-        if (isPromise(maybePromise)) {
-          return maybePromise.then(() => _cb(), err => _cb(err));
+        if (isPromiseLike(maybePromiseLike)) {
+          return maybePromiseLike.then((res) => _cb(res), err => _cb(err));
+        }
+
+        if (maybePromiseLike instanceof Kareem.overwriteResult) {
+          args = maybePromiseLike.args;
         }
 
         if (++currentPost >= numPosts) {
           return callback.apply(null, [error].concat(args));
         }
 
-        next(error);
+        next();
       }
     }
   };
@@ -219,12 +262,17 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
 };
 
 Kareem.prototype.execPostSync = function(name, context, args) {
-  const posts = get(this._posts, name, []);
+  const posts = this._posts.get(name) || [];
   const numPosts = posts.length;
 
   for (let i = 0; i < numPosts; ++i) {
-    posts[i].fn.apply(context, args || []);
+    const res = posts[i].fn.apply(context, args || []);
+    if (res instanceof Kareem.overwriteResult) {
+      args = res.args;
+    }
   }
+
+  return args;
 };
 
 Kareem.prototype.createWrapperSync = function(name, fn) {
@@ -234,37 +282,33 @@ Kareem.prototype.createWrapperSync = function(name, fn) {
 
     var toReturn = fn.apply(this, arguments);
 
-    kareem.execPostSync(name, this, [toReturn]);
+    const result = kareem.execPostSync(name, this, [toReturn]);
 
-    return toReturn;
+    return result[0];
   };
 }
 
 function _handleWrapError(instance, error, name, context, args, options, callback) {
   if (options.useErrorHandlers) {
-    var _options = { error: error };
-    return instance.execPost(name, context, args, _options, function(error) {
+    return instance.execPost(name, context, args, { error: error }, function(error) {
       return typeof callback === 'function' && callback(error);
     });
   } else {
-    return typeof callback === 'function' ?
-      callback(error) :
-      undefined;
+    return typeof callback === 'function' && callback(error);
   }
 }
 
 Kareem.prototype.wrap = function(name, fn, context, args, options) {
   const lastArg = (args.length > 0 ? args[args.length - 1] : null);
-  const argsWithoutCb = typeof lastArg === 'function' ?
-    args.slice(0, args.length - 1) :
-    args;
+  let argsWithoutCb = Array.from(args);
+  typeof lastArg === 'function' && argsWithoutCb.pop();
   const _this = this;
 
   options = options || {};
   const checkForPromise = options.checkForPromise;
 
   this.execPre(name, context, args, function(error) {
-    if (error) {
+    if (error && !(error instanceof Kareem.skipWrappedFunction)) {
       const numCallbackParams = options.numCallbackParams || 0;
       const errorArgs = options.contextParameter ? [context] : [];
       for (var i = errorArgs.length; i < numCallbackParams; ++i) {
@@ -274,17 +318,22 @@ Kareem.prototype.wrap = function(name, fn, context, args, options) {
         options, lastArg);
     }
 
-    const end = (typeof lastArg === 'function' ? args.length - 1 : args.length);
     const numParameters = fn.length;
     let ret;
-    try {
-      ret = fn.apply(context, args.slice(0, end).concat(_cb));
-    } catch (err) {
-      return _cb(err);
+
+    if (error instanceof Kareem.skipWrappedFunction) {
+      ret = error.args[0];
+      return _cb(null, ...error.args);
+    } else {
+      try {
+        ret = fn.apply(context, argsWithoutCb.concat(_cb));
+      } catch (err) {
+        return _cb(err);
+      }
     }
 
     if (checkForPromise) {
-      if (ret != null && typeof ret.then === 'function') {
+      if (isPromiseLike(ret)) {
         // Thenable, use it
         return ret.then(
           res => _cb(null, res),
@@ -294,14 +343,14 @@ Kareem.prototype.wrap = function(name, fn, context, args, options) {
 
       // If `fn()` doesn't have a callback argument and doesn't return a
       // promise, assume it is sync
-      if (numParameters < end + 1) {
+      if (numParameters < argsWithoutCb.length + 1) {
         return _cb(null, ret);
       }
     }
 
     function _cb() {
-      const args = arguments;
-      const argsWithoutError = Array.prototype.slice.call(arguments, 1);
+      const argsWithoutError = Array.from(arguments);
+      argsWithoutError.shift();
       if (options.nullResultByDefault && argsWithoutError.length === 0) {
         argsWithoutError.push(null);
       }
@@ -311,15 +360,12 @@ Kareem.prototype.wrap = function(name, fn, context, args, options) {
           argsWithoutError, options, lastArg);
       } else {
         _this.execPost(name, context, argsWithoutError, function() {
-          if (arguments[0]) {
-            return typeof lastArg === 'function' ?
-              lastArg(arguments[0]) :
-              undefined;
+          if (lastArg === null) {
+            return;
           }
-
-          return typeof lastArg === 'function' ?
-            lastArg.apply(context, arguments) :
-            undefined;
+          arguments[0]
+            ? lastArg(arguments[0])
+            : lastArg.apply(context, arguments)
         });
       }
     }
@@ -372,28 +418,26 @@ Kareem.prototype.createWrapper = function(name, fn, context, options) {
     // Fast path: if there's no hooks for this function, just return the
     // function wrapped in a nextTick()
     return function() {
-      process.nextTick(() => fn.apply(this, arguments));
+      nextTick(() => fn.apply(this, arguments));
     };
   }
   return function() {
     var _context = context || this;
-    var args = Array.prototype.slice.call(arguments);
-    _this.wrap(name, fn, _context, args, options);
+    _this.wrap(name, fn, _context, Array.from(arguments), options);
   };
 };
 
 Kareem.prototype.pre = function(name, isAsync, fn, error, unshift) {
   let options = {};
-  if (typeof isAsync === 'object' && isAsync != null) {
+  if (typeof isAsync === 'object' && isAsync !== null) {
     options = isAsync;
     isAsync = options.isAsync;
   } else if (typeof arguments[1] !== 'boolean') {
-    error = fn;
     fn = isAsync;
     isAsync = false;
   }
 
-  const pres = get(this._pres, name, []);
+  const pres = this._pres.get(name) || [];
   this._pres.set(name, pres);
 
   if (isAsync) {
@@ -415,7 +459,7 @@ Kareem.prototype.pre = function(name, isAsync, fn, error, unshift) {
 };
 
 Kareem.prototype.post = function(name, options, fn, unshift) {
-  const hooks = get(this._posts, name, []);
+  const hooks = this._posts.get(name) || [];
 
   if (typeof options === 'function') {
     unshift = !!fn;
@@ -456,7 +500,7 @@ Kareem.prototype.merge = function(other, clone) {
   var ret = clone ? this.clone() : this;
 
   for (let key of other._pres.keys()) {
-    const sourcePres = get(ret._pres, key, []);
+    const sourcePres = ret._pres.get(key) || [];
     const deduplicated = other._pres.get(key).
       // Deduplicate based on `fn`
       filter(p => sourcePres.map(_p => _p.fn).indexOf(p.fn) === -1);
@@ -466,7 +510,7 @@ Kareem.prototype.merge = function(other, clone) {
     ret._pres.set(key, combined);
   }
   for (let key of other._posts.keys()) {
-    const sourcePosts = get(ret._posts, key, []);
+    const sourcePosts = ret._posts.get(key) || [];
     const deduplicated = other._posts.get(key).
       filter(p => sourcePosts.indexOf(p) === -1);
     ret._posts.set(key, sourcePosts.concat(deduplicated));
@@ -475,28 +519,21 @@ Kareem.prototype.merge = function(other, clone) {
   return ret;
 };
 
-function get(map, key, def) {
-  if (map.has(key)) {
-    return map.get(key);
-  }
-  return def;
-}
-
 function callMiddlewareFunction(fn, context, args, next) {
-  let maybePromise;
+  let maybePromiseLike;
   try {
-    maybePromise = fn.apply(context, args);
+    maybePromiseLike = fn.apply(context, args);
   } catch (error) {
     return next(error);
   }
 
-  if (isPromise(maybePromise)) {
-    maybePromise.then(() => next(), err => next(err));
+  if (isPromiseLike(maybePromiseLike)) {
+    maybePromiseLike.then(() => next(), err => next(err));
   }
 }
 
-function isPromise(v) {
-  return v != null && typeof v.then === 'function';
+function isPromiseLike(v) {
+  return (typeof v === 'object' && v !== null && typeof v.then === 'function');
 }
 
 function decorateNextFn(fn) {
@@ -510,8 +547,12 @@ function decorateNextFn(fn) {
     called = true;
     // Make sure to clear the stack so try/catch doesn't catch errors
     // in subsequent middleware
-    return process.nextTick(() => fn.apply(_this, arguments));
+    return nextTick(() => fn.apply(_this, arguments));
   };
 }
 
+const nextTick = typeof process === 'object' && process !== null && process.nextTick || function nextTick(cb) { 
+  setTimeout(cb, 0); 
+}
+
 module.exports = Kareem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kareem",
-  "version": "2.3.3",
+  "version": "2.4.0",
   "description": "Next-generation take on pre/post function hooks",
   "main": "index.js",
   "scripts": {
@@ -14,8 +14,8 @@
   "devDependencies": {
     "acquit": "1.x",
     "acquit-ignore": "0.1.x",
-    "nyc": "11.x",
-    "mocha": "5.x"
+    "mocha": "9.2.0",
+    "nyc": "15.1.0"
   },
   "author": "Valeri Karpov <val@karpov.io>",
   "license": "Apache-2.0"

package/test/post.test.js

@@ -165,6 +165,71 @@ describe('execPost', function() {
       done();
     });
   });
+
+  it('supports overwriteResult', function(done) {
+    hooks.post('cook', function(eggs, callback) {
+      callback(Kareem.overwriteResult(5));
+    });
+
+    hooks.post('cook', function(eggs, callback) {
+      assert.equal(eggs, 5);
+      callback();
+    });
+
+    var options = {};
+    hooks.execPost('cook', null, [4], options, function(error, eggs) {
+      assert.equal(eggs, 5);
+      done();
+    });
+  });
+
+  it('supports sync returning overwriteResult', function(done) {
+    hooks.post('cook', function() {
+      return Kareem.overwriteResult(5);
+    });
+
+    hooks.post('cook', function(eggs, callback) {
+      assert.equal(eggs, 5);
+      callback();
+    });
+
+    var options = {};
+    hooks.execPost('cook', null, [4], options, function(error, eggs) {
+      assert.ifError(error);
+      assert.equal(eggs, 5);
+      done();
+    });
+  });
+
+  it('supports sync overwriteResult', function() {
+    hooks.post('cook', function(eggs) {
+      return Kareem.overwriteResult(5);
+    });
+
+    hooks.post('cook', function(eggs) {
+      assert.equal(eggs, 5);
+    });
+
+    var options = {};
+    const res = hooks.execPostSync('cook', null, [4], options);
+    assert.deepEqual(res, [5]);
+  });
+
+  it('supports overwriteResult with promises', function(done) {
+    hooks.post('cook', function(eggs) {
+      return Promise.resolve(Kareem.overwriteResult(5));
+    });
+
+    hooks.post('cook', function(eggs) {
+      assert.equal(eggs, 5);
+    });
+
+    var options = {};
+    hooks.execPost('cook', null, [4], options, function(error, eggs) {
+      assert.equal(eggs, 5);
+      done();
+    });
+  }); 
 });
 
 describe('execPostSync', function() {

package/test/pre.test.js

@@ -307,6 +307,24 @@ describe('execPre', function() {
       done();
     });
   });
+
+  it('supports skipWrappedFunction', function(done) {
+    var execed = {};
+
+    hooks.pre('cook', function(callback) {
+      callback(Kareem.skipWrappedFunction(42));
+    });
+
+    hooks.pre('cook', function() {
+      execed.second = true;
+    });
+
+    hooks.execPre('cook', null, function(err) {
+      assert.ok(execed.second);
+      assert.ok(err instanceof Kareem.skipWrappedFunction);
+      done();
+    });
+  });
 });
 
 describe('execPreSync', function() {

package/test/wrap.test.js

@@ -287,6 +287,91 @@ describe('wrap()', function() {
       25);
   });
 
+  it('supports overwriteResult', function(done) {
+    hooks.post('cook', function(eggs, callback) {
+      callback(Kareem.overwriteResult(5));
+    });
+
+    const args = [(err, res) => {
+      assert.ifError(err);
+      assert.equal(res, 5);
+      done();
+    }];
+
+    hooks.wrap(
+      'cook',
+      function(callback) {
+        callback(null, 4);
+      },
+      null,
+      args);
+  });
+
+  it('supports skipWrappedFunction', function(done) {
+    const execed = {};
+    hooks.pre('cook', function pre(callback) {
+      execed.pre = true;
+      callback(Kareem.skipWrappedFunction(3));
+    });
+
+    hooks.post('cook', function(res, callback) {
+      assert.equal(res, 3);
+      execed.post = true;
+      callback();
+    });
+
+    const args = [(err, res) => {
+      assert.ifError(err);
+      assert.equal(res, 3);
+      assert.ok(execed.pre);
+      assert.ok(execed.post);
+      assert.ok(!execed.wrapped);
+      done();
+    }];
+
+    hooks.wrap(
+      'cook',
+      function wrapped(callback) {
+        execed.wrapped = true;
+        callback();
+      },
+      null,
+      args);
+  });
+
+  it('supports skipWrappedFunction with arguments', function(done) {
+    const execed = {};
+    hooks.pre('cook', function pre(callback, arg) {
+      execed.pre = true;
+      assert.strictEqual(arg, 4);
+      callback(Kareem.skipWrappedFunction(3));
+    });
+
+    hooks.post('cook', function(res, callback) {
+      assert.equal(res, 3);
+      execed.post = true;
+      callback();
+    });
+
+    const args = [4, (err, res) => {
+      assert.ifError(err);
+      assert.equal(res, 3);
+      assert.ok(execed.pre);
+      assert.ok(execed.post);
+      assert.ok(!execed.wrapped);
+      done();
+    }];
+
+    hooks.wrap(
+      'cook',
+      function wrapped(arg, callback) {
+        execed.wrapped = true;
+        callback();
+      },
+      null,
+      args);
+  });
+
   it('handles post errors with no args', function(done) {
     hooks.pre('cook', function(done) {
       obj.waffles = false;
@@ -363,4 +448,17 @@ describe('wrap()', function() {
     assert.equal(calledFn, 1);
     assert.equal(calledPost, 1);
   });
+
+  it('sync wrappers with overwriteResult', function() {
+    hooks.pre('cook', function() {
+    });
+
+    hooks.post('cook', function() {
+      return Kareem.overwriteResult(5);
+    });
+
+    const wrapper = hooks.createWrapperSync('cook', function() { return 4; });
+
+    assert.strictEqual(wrapper(), 5);
+  });
 });