kareem 2.3.4 → 2.4.1

package/.eslintrc.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@masteringjs"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2020
+  },
+  "env": {
+    "node": true,
+    "es6": true
+  },
+  "rules": {
+    "no-var": "off",
+    "prefer-const": "off"
+  }
+}

package/.github/workflows/test.yml

@@ -0,0 +1,47 @@
+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]
+    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
+
+  lint:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [18]
+        os: [ubuntu-20.04]
+    name: Lint
+    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 run lint

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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)
 

package/docs.js

@@ -1,3 +1,5 @@
+'use strict';
+
 var acquit = require('acquit');
 
 require('acquit-ignore')();

package/index.js

@@ -5,6 +5,22 @@ 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;
@@ -17,9 +33,10 @@ Kareem.prototype.execPre = function(name, context, args, callback) {
   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);
       }
     }
 
@@ -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));
     });
   }
@@ -153,6 +178,13 @@ Kareem.prototype.execPost = function(name, context, args, options, callback) {
       if (post.length === numArgs + 2) {
         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,16 +233,25 @@ 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 instanceof Kareem.overwriteResult ? res : null);
+            },
+            err => _cb(err)
+          );
+        }
+
+        if (maybePromiseLike instanceof Kareem.overwriteResult) {
+          args = maybePromiseLike.args;
         }
 
         if (++currentPost >= numPosts) {
@@ -223,8 +271,13 @@ Kareem.prototype.execPostSync = function(name, context, args) {
   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,11 +287,11 @@ 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) {
@@ -252,16 +305,15 @@ function _handleWrapError(instance, error, name, context, args, options, callbac
 
 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) {
@@ -271,17 +323,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),
@@ -291,7 +348,7 @@ 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);
       }
     }
@@ -308,15 +365,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);
         });
       }
     }
@@ -369,7 +423,7 @@ 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() {
@@ -471,20 +525,20 @@ Kareem.prototype.merge = function(other, clone) {
 };
 
 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) {
@@ -498,8 +552,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,9 +1,10 @@
 {
   "name": "kareem",
-  "version": "2.3.4",
+  "version": "2.4.1",
   "description": "Next-generation take on pre/post function hooks",
   "main": "index.js",
   "scripts": {
+    "lint": "eslint .",
     "test": "mocha ./test/*",
     "test-travis": "nyc mocha ./test/*"
   },
@@ -12,8 +13,10 @@
     "url": "git://github.com/vkarpov15/kareem.git"
   },
   "devDependencies": {
+    "@masteringjs/eslint-config": "0.0.1",
     "acquit": "1.x",
     "acquit-ignore": "0.1.x",
+    "eslint": "8.15.0",
     "mocha": "9.2.0",
     "nyc": "15.1.0"
   },

package/test/examples.test.js

@@ -1,4 +1,7 @@
+'use strict';
+
 var assert = require('assert');
+const { beforeEach, describe, it } = require('mocha');
 var Kareem = require('../');
 
 /* Much like [hooks](https://npmjs.org/package/hooks), kareem lets you define

package/test/misc.test.js

@@ -2,6 +2,7 @@
 
 const assert = require('assert');
 const Kareem = require('../');
+const { describe, it } = require('mocha');
 
 describe('hasHooks', function() {
   it('returns false for toString (Automattic/mongoose#6538)', function() {
@@ -14,7 +15,6 @@ describe('merge', function() {
   it('handles async pres if source doesnt have them', function() {
     const k1 = new Kareem();
     k1.pre('cook', true, function(next, done) {
-      execed.first = true;
       setTimeout(
         function() {
           done('error!');

package/test/post.test.js

@@ -2,6 +2,7 @@
 
 const assert = require('assert');
 const Kareem = require('../');
+const { beforeEach, describe, it } = require('mocha');
 
 describe('execPost', function() {
   var hooks;
@@ -165,6 +166,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

@@ -2,6 +2,7 @@
 
 const assert = require('assert');
 const Kareem = require('../');
+const { beforeEach, describe, it } = require('mocha');
 
 describe('execPre', function() {
   var hooks;
@@ -307,6 +308,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

@@ -1,5 +1,8 @@
+'use strict';
+
 var assert = require('assert');
 var Kareem = require('../');
+const { beforeEach, describe, it } = require('mocha');
 
 describe('wrap()', function() {
   var hooks;
@@ -287,6 +290,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 +451,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);
+  });
 });

package/gulpfile.js

@@ -1,18 +0,0 @@
-var gulp = require('gulp');
-var mocha = require('gulp-mocha');
-var config = require('./package.json');
-var jscs = require('gulp-jscs');
-
-gulp.task('mocha', function() {
-  return gulp.src('./test/*').
-    pipe(mocha({ reporter: 'dot' }));
-});
-
-gulp.task('jscs', function() {
-  return gulp.src('./index.js').
-    pipe(jscs(config.jscsConfig));
-});
-
-gulp.task('watch', function() {
-  gulp.watch('./index.js', ['jscs', 'mocha']);
-});