hooks.js

Hooks library provides full support for adding pre and post hooks to independent functions and functions in objects.

I. Installation

npm install hooks.js --save

Use it like this:

var hooks = require('hooks.js');

// Hookify!
hooks.hookify(myObject);

// set hook before function
myObject.someFunction.$hooks.pre(function($input, $inspect) {...});

// set hook after function
myObject.someFunction.$hooks.post(function($input, $inspect, $output) {...});

// now hooks are called before and after someFunction
myObject.someFunction();

There is access to arguments inserted to function when it is called ($input) in both .pre() and .post() hooks.

There is output value returned from hookified function for .post() hook only ($output) which can be naturally optionally overwritten by .post() hook with simple return "myNewValue"; statement (if value in return statement is anything but undefined, if undefined is returned, hookified function will still return original value).

Also you've got some great references in $inspect object for both .pre() and .post() hooks, if it's setter or getter, property name is resolved (e.g. getName -> $inspect.property (name), setMyScores -> $inspect.property (myScores) ).

Use cases

Hooks can be very useful for hooking setters and getters if you don't want to put too much complex logic inside them in the class:

function myClass () {

  this._constructor = function() {
    hooks.hookify(this);
    this.setName.$hooks.pre(function($input, $inspect){
      if ($input[0].length < 5)// reference to firstArgument of myClass.setName(firstArgument)
        throw new Error($inspect.property + ' is too short'); // name is too short
    });
    this.getName.$hooks.post(function($input, $inspect, $output){
      return $output.toUpperCase(); // overwrite original output, e.g. "John" would change to "JOHN"
    });
    this.getName.$hooks.pre(function($input, $inspect){
      if (this[$inspect.property] === undefined) // this.name === undefined?
        throw new Error($inspect.property + ' is undefined'); // name is undefined
    });
  };

  this.setName = function(name) {
    this.name = name;
    return this;
  };

  this.getName = function() {
    return this.name;
  };

}

You can also add hooks in batch on only matching functions:

hooks.hookify(myObject);

myObject.$hooks.pre('^get(.*?)$', function($input, $inspect) {
  console.log('Getter fired');
});

myObject.$hooks.pre(new RegExp('^get(.*?)$'), function($input, $inspect) {
  var propertyName = $inspect.property;
  if (this[propertyName] === undefined)
    throw new Error(propertyName + ' property is undefined');
});

myObject.$hooks.$getters.pre(function($input, $inspect) {
  // Do something
});

To see logs of hooks actions in console, you can call hooks.setLog(true);.

II. API - ASSIGN

mount

Arguments: (@original_function:Array, @usePromise:Boolean(optional), @context:Object(optional))

myFunction = hooks.mount(myFunction);

hookify

Arguments: (@object:Object, @regex:String||RegExp(optional), @usePromise:Boolean(optional))

hooks.hookify(myObject);

or

hooks.hookify(myObject, 'getters');

or

hooks.hookify(myObject, '^get(.*?)$');

II. API - FUNCTION

You can use them on function on which you called first:

myFunction = hooks.mount(myFunction);

or

hooks.hookify(myObject);
var myFunction = myObject.myFunction;

pre

before

Arguments: (@prehook_callback:Function)

myFunction.$hooks.pre(function($input, $inspect){
  // Something
});

post

after

Arguments: (@posthook_callback:Function)

myFunction.$hooks.post(function($input, $inspect, $output){
  // Something
});

clean

Arguments: none

myFunction.$hooks.clean();

III. API - OBJECT

pre

before

Arguments: (@regex:String||RegExp, @prehook_callback:Function)

myObject.$hooks.pre('^get(.*?)$', function($input, $inspect) {
  // Something
});
// OR
myObject.$hooks.pre(new RegExp('^get(.*?)$'), function($input, $inspect) {
  // Something
});
// OR
myObject.$hooks.$getters.pre(function($input, $inspect) {
  // Something
});
// OR
myObject.$hooks.$setters.pre(function($input, $inspect) {
  // Something
});

post

after

Arguments: (@regex:String||RegExp, @posthook_callback:Function)

myObject.$hooks.post(new RegExp('^set(.*?)$'), function($input, $inspect, $output) {
  // Something
});

IV. Examples

1) Hookify

If you want to add hooks to all functions in the object:

var hooks = require('hooks.js');

...

var myCustomObject = {
  this.myFunction = function(arg1, arg2) {
  }
  this.myOtherFunction = function() {
  }
};

...

// Hookify!
hooks.hookify(myClassObj);

...

// Set custom hook actions
myCustomObject.myFunction.$hooks.pre(function($input, $inspect) {
  console.log('Do sth before');
});
myCustomObject.myOtherFunction.$hooks.post(function($input, $inspect, $output) {
  console.log('Do sth after');
});

...

// Call functions
myClassObj.myFunction();
myClassObj.myOtherFunction();
myClassObj.myFunction();

2) Mount

If you want to add hooks to only one specified function:

var myFunction = function  (user_name) {
  // Something
}

...

// Mount hook to the function
myFunction = hooks.mount(myFunction);

...

// Set custom hook actions
myFunction.$hooks.pre(function($input, $inspect) {
  console.log('Do sth before');
});

...

// Call function
myFunction('Anna');

License

MIT