call-hook

call-hook

Hook function calls with other functions.

Prehooks execute before the callee (aka target) function executes and may alter the arguments sent to the callee or abort callee execution, while posthooks execute after the callee function, receive the same arguments as the callee, and may also access it's return value.

example

var pre  = require('call-hook/pre'), // or require('call-hook').post
    post = require('call-hook/post') // or require('call-hook').pre

function hello (name) {
    console.log('hello ' + name)
}

var quickVisit = post(hello, function goodbye (name) {
    console.log('goodbye ' + name)
})

var shakeGreet = pre(hello, function handshake () {
    console.log('handshake')
})

hello('Jason') // hello Jason

console.log('\n')

quickVisit('Jason') // hello Jason
                    // goodbye Jason

console.log('\n')

shakeGreet('Jason') // handshake
                    // hello Anonymous

api

var pre  = require('call-hook/pre'), // or require('call-hook').post
    post = require('call-hook/post') // or require('call-hook').pre

hookedFunc = pre(callee, preCall)

Returns a new function, hookedFunc, which executes the preCall function prior to executing the callee function. If preCall returns an Array, then that array will be applied to callee as arguments, otherwise both preCall and callee functions will receive the arguments of the hookedFunc function call. The callee is executed in an undefined context, while the preCall function is executed in the context of an object that offers the abort function. Calling abort will prevent callee from being called. The return value of the hookedFunc function call will be the return value of callee, unless abort was called, in which case the returnValue of hookedFunc will be the 1st argument to abort.

Example of altering arguments being sent to callee:

var pre  = require('call-hook/pre')

function roll (sides) {
    return Math.ceil(Math.random() * sides)
}

var rollD10 = pre(roll, function d10 () {
    return [10]
})

console.log('10-sided die roll result: ' + rollD10())

Example of aborting:

var pre  = require('call-hook/pre')

function roll (sides) {
    return Math.ceil(Math.random() * sides)
}

// hijack roll, if a 20 sided die is requested, always return 20
var roll = pre(roll, function loadedD20 (sides) {
    if (sides === 20) return this.abort(20)
})

console.log('10-sided die roll result: ' + roll(10)) // 1 - 10
console.log('20-sided die roll result: ' + roll(20)) // always 20

hookedFunc = post(callee, postCall)

Returns a new function, hookedFunc which executes the callee function, followed by the postCall function. Both functions receive the same arguments passed to hookedFunc. The callee function is executed in an undefined context, while the postCall is executed in the context of an object that offers previousReturnValue, which may be used to access the return value of the callee function. The return value of hookedFunc is the return value of postCall. If you do not wish to alter the return value of callee, then it's important to return this.previousReturnValue in postCall.

Example of accessing previous return value:

var post = require('call-hook/post')

function roll (sides) {
    return Math.ceil(Math.random() * sides)
}

var printDieRoll = post(roll, function print (sides) {
    console.log(sides + '-sided die roll result: ' + this.previousReturnValue)
    return this.previousReturnValue
})

printDieRoll(6)

install

With npm do:

npm install --save call-hook

testing

npm test

Or to run tests in phantom: npm run phantom

coverage

npm run view-cover

This will output a textual coverage report.

npm run open-cover

This will open an HTML coverage report in the default browser.