JavaScript 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)
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)
</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)
</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');
hooker.hook(Math, "max", function() {
console.log(arguments.length + " arguments passed");
});
Math.max(5, 6, 7)
hooker.unhook(Math, "max");
Math.max(5, 6, 7)
hooker.hook(Math, "max", function() {
if (arguments.length === 0) {
return hooker.override(9000);
}
});
Math.max(5, 6, 7)
Math.max()
hooker.hook(Math, "max", {
once: true,
pre: function() {
console.log("Init something here");
}
});
Math.max(5, 6, 7)
Math.max(5, 6, 7)
hooker.hook(Math, "max", {
pre: function() {
var args = [].map.call(arguments, function(num) {
return num * 2;
});
return hooker.filter(this, args);
}
});
Math.max(5, 6, 7)
hooker.hook(Math, "max", {
post: function(result) {
return hooker.override(result * 100);
}
});
Math.max(5, 6, 7)
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);
result
result = Math.ceil(3.456);
result
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/