HOOKZ

This one was inspired by my favorite hooking system. The best if you will. Hooks API of the ProcessWire CMS.

ProcessWire Hooks + Backbone.Events = hookz

What this have to do with the Backbone.Events, you might ask. Well, I believe that the code for best hooking system I know should be written by one of the best JavaScript coders I am aware of. So I took the code for Backbone.Events and tweaked it to behave like ProcessWire's Hooks API. I even took all the tests for Backbone.Events for testing this very module. And, of course, I added some more.

Install

Install with npm

$ npm install hookz --save

Usage

var hookz = require('hookz');
 
var hooker = {
  foo : function (hookEv) {
    console.log(hookEv.returnValue + ' boo');
  }
};
 
var hookable = {
  ___bar : function () {
    return 'baz';
  }
}
 
hookz.call(hooker);
hookz.call(hookable);
 
hooker.addHook(hookable, 'bar', hooker.foo);
 
hookable.bar();

//=> baz boo

API

Constructer

To make a JavaScript object hookable and/or hooker (being able to hook) you call hookz on it. All methods that are properly prefixed will be hookable. Then you call the hookable methods without the prefix and trigger all attached hook methods.

var obj = {
  ___a : function () {}
};

hookz.call(obj);

obj.a(); // This will trigger all the attached hooks

If you wish to call a hookable method without triggering the hooks attached to it, then you call the method with the prefix. Like this...

obj.___a(); // This will not trigger any attached hooks

The syntax is:

hookz.call(obj [, prefix]);

obj is an object that you want to turn into a hookz object. Which makes it hookable or being able to add hooks into other hookable objects. prefix (optional) is used to determine if the method is hookable. Default is ___ (three underscores).

Note: The methods defined after the call on hookz will not be hookable. First you define your desired object and it's methods, then you call hookz on them. If you want to define hookable methods on the runtime, you can do that with addHook method, see below.

addHook

Adds a hook on a hookable method. Every hookz object has an addHook method.

obj.addHook(obj, 'a', function () {
  console.log('The world is mine!');
});
 
obj.a();
// => The world is mine!

The syntax is:

obj.addHook(obj, methodName, callback [, context]);

obj is a hookable object. methodName is a name of the method that you want to attach hooks into. callback is a function to be called. context is a context for the callback. Defaults to the object that attaches a hook.

You can provide multiple names at once to attach a hook to several hookable methods. The names should be seperated with space.

obj.addHook(obj, 'name1 name2 name3', function () {});

hookz also supports a map syntax for attaching hooks, as an alternative.

obj.addHook(obj, {
  name : function () {},
  name1 : function () {},
  name2 : function () {} 
});

You can provide a context as a third argument when you are attaching hooks via object map syntax.

obj.addHook(obj, {name : function () {}}, context);

If you want to add hookable methods at the runtime, you can do so with addHook method.

obj.addHook(obj, 'someName', function () {});

If obj has no method or property called someName it gets one and it is also hookable.

removeHook

You can remove the hooks that you have attached with removeHook method.

The syntax is:

obj.removeHook([obj] [, name] [, callback] [, context]);

You can remove all the hooks that was attached by an object if you call removeHook with no arguments. Or provide any argument to be more precise. You even can remove hooks with map syntax.

obj.removeHook(obj, {
  name1 : callback1,
  name2 : callback2
});

You can remove all hooks on specific context

obj.removeHook(null, null, context);

addHookOnce

You can attach a hook so it fires just once with addHookOnce. This one supports all the syntax style as the addHook method.

var counter = 0;
var obj = {
  ___a : function () { return this; }
};

hookz.call(obj);

obj.addHookOnce(obj, 'a', function () {
  counter += 1;
});

obj.a().a().a().a();

console.log('counter is: ' + counter);
//=> counter is 1

You can also use map syntax with addHookOnce

obj.addHookOnce(obj, {
  a : function () {},
  b : function () {}
});

// Each calback will be invoked once

AddHookBefore & AddHookAfter

If you need a specific hook to run after or before the hookable method, then you can use addHookAfter and addHookBefore methods.

obj.addHookBefore(obj, 'a', function () {
  console.log('the `a` method is about to run');
});

Both addHookAfter and addHookBefore support all the syntactic sugar that the addHook method does.

HookEvent

All attached hook callbacks get only one argument. A HookEvent object. This object is one of the key concepts of the hookz. It allows you to modify the behavior of the process on the fly.

HookEvent.args

The args property of the HookEvent contains the arguments that were passed into hookable method when invoked.

obj.addHook(obj, 'a', function (HookEvent) {
  console.log(HookEvent.args[0]);
});

obj.a('foo');
//=> foo

You can modify the arguments for the next hooks in the chain that were attached into the same hookable method.

obj.addHook(obj, 'a', function (HookEv) {
  console.log('callback1: ' + HookEv.args[0]);
  HookEv.args[0] = 'bar';
});

obj.addHook(obj, 'a', function (HookEv) {
  console.log('callback2: ' + HookEv.args[0]);
});

obj.a('foo');

//=> callback1: foo
//=> callback2: bar

With the before hooks are be able to modify the arguments of the hookable method before it is invoked.

var obj = {
  ___a : function (arg) {
    console.log(arg);
  }
};

hookz.call(obj);

obj.addHookBefore(obj, 'a', function (hookEv) {
  hookEv.args[0] = 'bar';
});

obj.a('foo');

//=> bar

HookEvent.returnValue

Another useful property that HookEvent has is a returnValue property. Now you can access the value returned by hookable method within all hooks that were attached to it.

var obj = {
  ___a : function () { return 'foo'; }
};

hookz.call(obj);

obj.addHookAfter(obj, 'a', function (HookEv) {
  console.log('obj.a returns ' + HookEv.returnValue);
});

obj.a();

//=> obj.a returns foo

Even more, you can change the returned value of the hookable method with the attached hook.

var obj = {
  ___a : function () { return 'The world is'; }
};

hookz.call(obj);

obj.addHookAfter(obj, 'a', function (HookEv) {
  HookEv.returnValue += ' mine!';
});

console.log(obj.a());

//=> The world is mine!;

HookEvent.obj

obj is another useful property of HookEvent. You can access the object into which the hook was attached to via HookEvent.obj.

var hooker = {};
var hookable = {
  ___a : function () {}
};

hookz.call(hooker);
hookz.call(hookable);

hooker.addHook(hookable, 'a', function (HookEv) {
  console.log(HookEv.obj === hookable);
  console.log(this === hooker);
});

hookable.a();
//=> true
//=> true

Remember? The default context for the callback is the object that attaches the hook.

Coming Soon

• Replace hooks.
• Remove underscore from dependencies.
• A demo app
• Thorough API docs

Test

The test files are not included into the npm package. You need to clone the repo to your machine.

$ git clone https://github.com/dadish/hookz.git
$ cd hookz
$ npm install
$ npm test

License

MIT

Credits

• Ryan Cramer, ProcessWire author
• Jeremy Ashkenas, Backbone author