kareem 2.6.3 → 3.1.0

package/README.md

@@ -5,80 +5,69 @@
 
 Re-imagined take on the [hooks](http://npmjs.org/package/hooks) module, meant to offer additional flexibility in allowing you to execute hooks whenever necessary, as opposed to simply wrapping a single function.
 
-Named for the NBA's all-time leading scorer Kareem Abdul-Jabbar, known for his mastery of the [hook shot](http://en.wikipedia.org/wiki/Kareem_Abdul-Jabbar#Skyhook)
+Named for the NBA's 2nd all-time leading scorer Kareem Abdul-Jabbar, known for his mastery of the [hook shot](http://en.wikipedia.org/wiki/Kareem_Abdul-Jabbar#Skyhook)
 
 <img src="http://upload.wikimedia.org/wikipedia/commons/0/00/Kareem-Abdul-Jabbar_Lipofsky.jpg" width="220">
 
+<!--DOCS START-->
+
 # API
 
 ## pre hooks
 
-Much like [hooks](https://npmjs.org/package/hooks), kareem lets you define
-pre and post hooks: pre hooks are called before a given function executes.
-Unlike hooks, kareem stores hooks and other internal state in a separate
-object, rather than relying on inheritance. Furthermore, kareem exposes
-an `execPre()` function that allows you to execute your pre hooks when
-appropriate, giving you more fine-grained control over your function hooks.
-
+NOTE: this file has some empty comment lines to workaround https://github.com/vkarpov15/acquit/issues/30
 
-#### It runs without any hooks specified
+### It runs without any hooks specified
 
 ```javascript
-hooks.execPre('cook', null, function() {
-  // ...
-});
+await hooks.execPre('cook', null);
 ```
 
-#### It runs basic serial pre hooks
-
-pre hook functions take one parameter, a "done" function that you execute
-when your pre hook is finished.
+### It runs basic serial pre hooks
 
+pre hook functions can return a promise that resolves when finished.
 
 ```javascript
-var count = 0;
+let count = 0;
 
-hooks.pre('cook', function(done) {
+hooks.pre('cook', function() {
   ++count;
-  done();
+  return Promise.resolve();
 });
 
-hooks.execPre('cook', null, function() {
-  assert.equal(1, count);
-});
+await hooks.execPre('cook', null);
+assert.equal(1, count);
 ```
 
-#### It can run multipe pre hooks
+### It can run multiple pre hooks
 
 ```javascript
-var count1 = 0;
-var count2 = 0;
+let count1 = 0;
+let count2 = 0;
 
-hooks.pre('cook', function(done) {
+hooks.pre('cook', function() {
   ++count1;
-  done();
+  return Promise.resolve();
 });
 
-hooks.pre('cook', function(done) {
+hooks.pre('cook', function() {
   ++count2;
-  done();
+  return Promise.resolve();
 });
 
-hooks.execPre('cook', null, function() {
-  assert.equal(1, count1);
-  assert.equal(1, count2);
-});
+await hooks.execPre('cook', null);
+assert.equal(1, count1);
+assert.equal(1, count2);
 ```
 
-#### It can run fully synchronous pre hooks
+### It can run fully synchronous pre hooks
 
 If your pre hook function takes no parameters, its assumed to be
 fully synchronous.
 
-
 ```javascript
-var count1 = 0;
-var count2 = 0;
+let count1 = 0;
+let count2 = 0;
 
 hooks.pre('cook', function() {
   ++count1;
@@ -88,86 +77,38 @@ hooks.pre('cook', function() {
   ++count2;
 });
 
-hooks.execPre('cook', null, function(error) {
-  assert.equal(null, error);
-  assert.equal(1, count1);
-  assert.equal(1, count2);
-});
+await hooks.execPre('cook', null);
+assert.equal(1, count1);
+assert.equal(1, count2);
 ```
 
-#### It properly attaches context to pre hooks
+### It properly attaches context to pre hooks
 
 Pre save hook functions are bound to the second parameter to `execPre()`
 
-
 ```javascript
-hooks.pre('cook', function(done) {
+hooks.pre('cook', function() {
   this.bacon = 3;
-  done();
 });
 
-hooks.pre('cook', function(done) {
+hooks.pre('cook', function() {
   this.eggs = 4;
-  done();
 });
 
-var obj = { bacon: 0, eggs: 0 };
+const obj = { bacon: 0, eggs: 0 };
 
 // In the pre hooks, `this` will refer to `obj`
-hooks.execPre('cook', obj, function(error) {
-  assert.equal(null, error);
-  assert.equal(3, obj.bacon);
-  assert.equal(4, obj.eggs);
-});
-```
-
-#### It can execute parallel (async) pre hooks
-
-Like the hooks module, you can declare "async" pre hooks - these take two
-parameters, the functions `next()` and `done()`. `next()` passes control to
-the next pre hook, but the underlying function won't be called until all
-async pre hooks have called `done()`.
-
-
-```javascript
-hooks.pre('cook', true, function(next, done) {
-  this.bacon = 3;
-  next();
-  setTimeout(function() {
-    done();
-  }, 5);
-});
-
-hooks.pre('cook', true, function(next, done) {
-  next();
-  var _this = this;
-  setTimeout(function() {
-    _this.eggs = 4;
-    done();
-  }, 10);
-});
-
-hooks.pre('cook', function(next) {
-  this.waffles = false;
-  next();
-});
-
-var obj = { bacon: 0, eggs: 0 };
-
-hooks.execPre('cook', obj, function() {
-  assert.equal(3, obj.bacon);
-  assert.equal(4, obj.eggs);
-  assert.equal(false, obj.waffles);
-});
+await hooks.execPre('cook', obj);
+assert.equal(3, obj.bacon);
+assert.equal(4, obj.eggs);
 ```
 
-#### It supports returning a promise
+### It supports returning a promise
 
 You can also return a promise from your pre hooks instead of calling
 `next()`. When the returned promise resolves, kareem will kick off the
 next middleware.
 
-
 ```javascript
 hooks.pre('cook', function() {
   return new Promise(resolve => {
@@ -178,80 +119,93 @@ hooks.pre('cook', function() {
   });
 });
 
-var obj = { bacon: 0 };
+const obj = { bacon: 0 };
+
+await hooks.execPre('cook', obj);
+assert.equal(3, obj.bacon);
+```
+
+### It supports filtering which hooks to run
+
+You can pass a `filter` option to `execPre()` to select which hooks
+to run. The filter function receives each hook object and should return
+`true` to run the hook or `false` to skip it.
+
+```javascript
+const execed = [];
+
+const fn1 = function() { execed.push('first'); };
+fn1.skipMe = true;
+hooks.pre('cook', fn1);
+
+const fn2 = function() { execed.push('second'); };
+hooks.pre('cook', fn2);
 
-hooks.execPre('cook', obj, function() {
-  assert.equal(3, obj.bacon);
+// Only runs fn2, skips fn1 because fn1.skipMe is true
+await hooks.execPre('cook', null, [], {
+  filter: hook => !hook.fn.skipMe
 });
+
+assert.deepStrictEqual(execed, ['second']);
 ```
 
 ## post hooks
 
-acquit:ignore:end
-
-#### It runs without any hooks specified
+### It runs without any hooks specified
 
 ```javascript
-hooks.execPost('cook', null, [1], function(error, eggs) {
-  assert.ifError(error);
-  assert.equal(1, eggs);
-  done();
-});
+const [eggs] = await hooks.execPost('cook', null, [1]);
+assert.equal(eggs, 1);
 ```
 
-#### It executes with parameters passed in
+### It executes with parameters passed in
 
 ```javascript
 hooks.post('cook', function(eggs, bacon, callback) {
-  assert.equal(1, eggs);
-  assert.equal(2, bacon);
+  assert.equal(eggs, 1);
+  assert.equal(bacon, 2);
   callback();
 });
 
-hooks.execPost('cook', null, [1, 2], function(error, eggs, bacon) {
-  assert.ifError(error);
-  assert.equal(1, eggs);
-  assert.equal(2, bacon);
-});
+const [eggs, bacon] = await hooks.execPost('cook', null, [1, 2]);
+assert.equal(eggs, 1);
+assert.equal(bacon, 2);
 ```
 
-#### It can use synchronous post hooks
+### It can use synchronous post hooks
 
 ```javascript
-var execed = {};
+const execed = {};
 
 hooks.post('cook', function(eggs, bacon) {
   execed.first = true;
-  assert.equal(1, eggs);
-  assert.equal(2, bacon);
+  assert.equal(eggs, 1);
+  assert.equal(bacon, 2);
 });
 
 hooks.post('cook', function(eggs, bacon, callback) {
   execed.second = true;
-  assert.equal(1, eggs);
-  assert.equal(2, bacon);
+  assert.equal(eggs, 1);
+  assert.equal(bacon, 2);
   callback();
 });
 
-hooks.execPost('cook', null, [1, 2], function(error, eggs, bacon) {
-  assert.ifError(error);
-  assert.equal(2, Object.keys(execed).length);
-  assert.ok(execed.first);
-  assert.ok(execed.second);
-  assert.equal(1, eggs);
-  assert.equal(2, bacon);
-});
+const [eggs, bacon] = await hooks.execPost('cook', null, [1, 2]);
+assert.equal(Object.keys(execed).length, 2);
+assert.ok(execed.first);
+assert.ok(execed.second);
+assert.equal(eggs, 1);
+assert.equal(bacon, 2);
 ```
 
-#### It supports returning a promise
+### It supports returning a promise
 
 You can also return a promise from your post hooks instead of calling
 `next()`. When the returned promise resolves, kareem will kick off the
 next middleware.
 
-
 ```javascript
-hooks.post('cook', function(bacon) {
+hooks.post('cook', function() {
   return new Promise(resolve => {
     setTimeout(() => {
       this.bacon = 3;
@@ -260,158 +214,165 @@ hooks.post('cook', function(bacon) {
   });
 });
 
-var obj = { bacon: 0 };
+const obj = { bacon: 0 };
+
+await hooks.execPost('cook', obj, [obj]);
+assert.equal(obj.bacon, 3);
+```
+
+### It supports filtering which hooks to run
+
+You can pass a `filter` option to `execPost()` to select which hooks
+to run. The filter function receives each hook object and should return
+`true` to run the hook or `false` to skip it.
 
-hooks.execPost('cook', obj, obj, function() {
-  assert.equal(obj.bacon, 3);
+```javascript
+const execed = [];
+
+const fn1 = function() { execed.push('first'); };
+fn1.skipMe = true;
+hooks.post('cook', fn1);
+
+const fn2 = function() { execed.push('second'); };
+hooks.post('cook', fn2);
+
+// Only runs fn2, skips fn1 because fn1.skipMe is true
+await hooks.execPost('cook', null, [], {
+  filter: hook => !hook.fn.skipMe
 });
+
+assert.deepStrictEqual(execed, ['second']);
 ```
 
 ## wrap()
 
-acquit:ignore:end
-
-#### It wraps pre and post calls into one call
+### It wraps pre and post calls into one call
 
 ```javascript
-hooks.pre('cook', true, function(next, done) {
-  this.bacon = 3;
-  next();
-  setTimeout(function() {
-    done();
-  }, 5);
+hooks.pre('cook', function() {
+  return new Promise(resolve => {
+    this.bacon = 3;
+    setTimeout(() => {
+      resolve();
+    }, 5);
+  });
 });
 
-hooks.pre('cook', true, function(next, done) {
-  next();
-  var _this = this;
-  setTimeout(function() {
-    _this.eggs = 4;
-    done();
-  }, 10);
+hooks.pre('cook', function() {
+  this.eggs = 4;
+  return Promise.resolve();
 });
 
-hooks.pre('cook', function(next) {
+hooks.pre('cook', function() {
   this.waffles = false;
-  next();
+  return Promise.resolve();
 });
 
 hooks.post('cook', function(obj) {
   obj.tofu = 'no';
 });
 
-var obj = { bacon: 0, eggs: 0 };
+const obj = { bacon: 0, eggs: 0 };
 
-var args = [obj];
-args.push(function(error, result) {
-  assert.ifError(error);
-  assert.equal(null, error);
-  assert.equal(3, obj.bacon);
-  assert.equal(4, obj.eggs);
-  assert.equal(false, obj.waffles);
-  assert.equal('no', obj.tofu);
+const args = [obj];
 
-  assert.equal(obj, result);
-});
-
-hooks.wrap(
+const result = await hooks.wrap(
   'cook',
-  function(o, callback) {
-    assert.equal(3, obj.bacon);
-    assert.equal(4, obj.eggs);
-    assert.equal(false, obj.waffles);
-    assert.equal(undefined, obj.tofu);
-    callback(null, o);
+  function(o) {
+    assert.equal(obj.bacon, 3);
+    assert.equal(obj.eggs, 4);
+    assert.equal(obj.waffles, false);
+    assert.equal(obj.tofu, undefined);
+    return o;
   },
   obj,
   args);
+
+assert.equal(obj.bacon, 3);
+assert.equal(obj.eggs, 4);
+assert.equal(obj.waffles, false);
+assert.equal(obj.tofu, 'no');
+assert.equal(result, obj);
 ```
 
 ## createWrapper()
 
-#### It wraps wrap() into a callable function
+### It wraps wrap() into a callable function
 
 ```javascript
-hooks.pre('cook', true, function(next, done) {
+hooks.pre('cook', function() {
   this.bacon = 3;
-  next();
-  setTimeout(function() {
-    done();
-  }, 5);
+  return Promise.resolve();
 });
 
-hooks.pre('cook', true, function(next, done) {
-  next();
-  var _this = this;
-  setTimeout(function() {
-    _this.eggs = 4;
-    done();
-  }, 10);
+hooks.pre('cook', function() {
+  return new Promise(resolve => {
+    this.eggs = 4;
+    setTimeout(function() {
+      resolve();
+    }, 10);
+  });
 });
 
-hooks.pre('cook', function(next) {
+hooks.pre('cook', function() {
   this.waffles = false;
-  next();
+  return Promise.resolve();
 });
 
 hooks.post('cook', function(obj) {
   obj.tofu = 'no';
 });
 
-var obj = { bacon: 0, eggs: 0 };
+const obj = { bacon: 0, eggs: 0 };
 
-var cook = hooks.createWrapper(
+const cook = hooks.createWrapper(
   'cook',
-  function(o, callback) {
+  function(o) {
     assert.equal(3, obj.bacon);
     assert.equal(4, obj.eggs);
     assert.equal(false, obj.waffles);
     assert.equal(undefined, obj.tofu);
-    callback(null, o);
+    return o;
   },
   obj);
 
-cook(obj, function(error, result) {
-  assert.ifError(error);
-  assert.equal(3, obj.bacon);
-  assert.equal(4, obj.eggs);
-  assert.equal(false, obj.waffles);
-  assert.equal('no', obj.tofu);
+const result = await cook(obj);
+assert.equal(obj.bacon, 3);
+assert.equal(obj.eggs, 4);
+assert.equal(obj.waffles, false);
+assert.equal(obj.tofu, 'no');
 
-  assert.equal(obj, result);
-});
+assert.equal(result, obj);
 ```
 
 ## clone()
 
-acquit:ignore:end
-
-#### It clones a Kareem object
+### It clones a Kareem object
 
 ```javascript
-var k1 = new Kareem();
+const k1 = new Kareem();
 k1.pre('cook', function() {});
 k1.post('cook', function() {});
 
-var k2 = k1.clone();
+const k2 = k1.clone();
 assert.deepEqual(Array.from(k2._pres.keys()), ['cook']);
 assert.deepEqual(Array.from(k2._posts.keys()), ['cook']);
 ```
 
 ## merge()
 
-#### It pulls hooks from another Kareem object
+### It pulls hooks from another Kareem object
 
 ```javascript
-var k1 = new Kareem();
-var test1 = function() {};
+const k1 = new Kareem();
+const test1 = function() {};
 k1.pre('cook', test1);
 k1.post('cook', function() {});
 
-var k2 = new Kareem();
-var test2 = function() {};
+const k2 = new Kareem();
+const test2 = function() {};
 k2.pre('cook', test2);
-var k3 = k2.merge(k1);
+const k3 = k2.merge(k1);
 assert.equal(k3._pres.get('cook').length, 2);
 assert.equal(k3._pres.get('cook')[0].fn, test2);
 assert.equal(k3._pres.get('cook')[1].fn, test1);