JarCastingJavaScript Hooker
Monkey-patch (hook) functions for debugging and stuff.
Getting Started
This code should work just fine in Node.js:
First, install the module with: npm install hooker
var hooker = require('hooker');
hooker.hook(Math, "max", function() {
console.log(arguments.length + " arguments passed");
});
Math.max(5, 6, 7) // logs: "3 arguments passed", returns 7
Or in the browser:
<script src="dist/ba-hooker.min.js"></script>
<script>
hook(Math, "max", function() {
console.log(arguments.length + " arguments passed");
});
Math.max(5, 6, 7) // logs: "3 arguments passed", returns 7
</script>
In the browser, you can attach Hooker's methods to any object.
<script>
this.exports = Bocoup.utils;
</script>
<script src="dist/ba-hooker.min.js"></script>
<script>
Bocoup.utils.hook(Math, "max", function() {
console.log(arguments.length + " arguments passed");
});
Math.max(5, 6, 7) // logs: "3 arguments passed", returns 7
</script>
Documentation
hooker.hook
Monkey-patch (hook) one or more methods of an object.
Signature:
hooker.hook(object, [ props, ] [options | prehookFunction])
props
The optional props argument can be a method name, array of method names or null. If null (or omitted), all enumerable methods of object will be hooked.
options
pre- (Function) a pre-hook function to be executed before the original function. Arguments passed into the method will be passed into the pre-hook function as well.post- (Function) a post-hook function to be executed after the original function. The original function's result is passed into the post-hook function as its first argument, followed by the method arguments.once- (Boolean) if true, auto-unhook the function after the first execution.passName- (Boolean) if true, pass the name of the method into the pre-hook function as its first arg (preceding all other arguments), and into the post-hook function as the second arg (after result but preceding all other arguments).
Returns:
An array of hooked method names.
hooker.unhook
Un-monkey-patch (unhook) one or more methods of an object.
Signature:
hooker.unhook(object [, props ])
props
The optional props argument can be a method name, array of method names or null. If null (or omitted), all methods of object will be unhooked.
Returns:
An array of unhooked method names.
hooker.orig
Get a reference to the original method from a hooked function.
Signature:
hooker.orig(object, props)
hooker.override
When a pre- or post-hook returns the result of this function, the value passed will be used in place of the original function's return value. Any post-hook override value will take precedence over a pre-hook override value.
Signature:
hooker.override(value)
hooker.preempt
When a pre-hook returns the result of this function, the value passed will be used in place of the original function's return value, and the original function will NOT be executed.
Signature:
hooker.preempt(value)
hooker.filter
When a pre-hook returns the result of this function, the context and arguments passed will be applied into the original function.
Signature:
hooker.filter(context, arguments)
Examples
See the unit tests for more examples.
var hooker = require('hooker');
// Simple logging.
hooker.hook(Math, "max", function() {
console.log(arguments.length + " arguments passed");
});
Math.max(5, 6, 7) // logs: "3 arguments passed", returns 7
hooker.unhook(Math, "max"); // (This is assumed between all further examples)
Math.max(5, 6, 7) // 7
// Returning hooker.override(value) overrides the original value.
hooker.hook(Math, "max", function() {
if (arguments.length === 0) {
return hooker.override(9000);
}
});
Math.max(5, 6, 7) // 7
Math.max() // 9000
// Auto-unhook after one execution.
hooker.hook(Math, "max", {
once: true,
pre: function() {
console.log("Init something here");
}
});
Math.max(5, 6, 7) // logs: "Init something here", returns 7
Math.max(5, 6, 7) // 7
// Filter `this` and arguments through a pre-hook function.
hooker.hook(Math, "max", {
pre: function() {
var args = [].map.call(arguments, function(num) {
return num * 2;
});
return hooker.filter(this, args); // thisValue, arguments
}
});
Math.max(5, 6, 7) // 14
// Modify the original function's result with a post-hook function.
hooker.hook(Math, "max", {
post: function(result) {
return hooker.override(result * 100);
}
});
Math.max(5, 6, 7) // 700
// Hook every Math method. Note: if Math's methods were enumerable, the second
// argument could be omitted. Since they aren't, an array of properties to hook
// must be explicitly passed. Non-method properties will be skipped.
// See a more generic example here: http://bit.ly/vvJlrS
hooker.hook(Math, Object.getOwnPropertyNames(Math), {
passName: true,
pre: function(name) {
console.log("=> Math." + name, [].slice.call(arguments, 1));
},
post: function(result, name) {
console.log("<= Math." + name, result);
}
});
var result = Math.max(5, 6, 7);
// => Math.max [ 5, 6, 7 ]
// <= Math.max 7
result // 7
result = Math.ceil(3.456);
// => Math.ceil [ 3.456 ]
// <= Math.ceil 4
result // 4
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.
Also, please don't edit files in the "dist" subdirectory as they are generated via grunt. You'll find source code in the "lib" subdirectory!
Release History
2012/01/09 - v0.2.3 - First official release.
License
Copyright (c) 2012 "Cowboy" Ben Alman
Licensed under the MIT license.
http://benalman.com/about/license/