{"_id":"hooker","_rev":"81378","name":"hooker","description":"Monkey-patch (hook) functions for debugging and stuff.","dist-tags":{"latest":"0.2.3"},"maintainers":[{"name":"cowboy","email":""}],"time":{"modified":"2021-06-03T10:25:58.000Z","created":"2012-01-31T17:12:07.821Z","0.2.3":"2012-01-31T17:12:07.821Z"},"users":{"tigefa":true,"fgribreau":true,"edin-m":true,"itonyyo":true,"hsrob":true,"zillding":true,"sirrah":true,"sopepos":true,"boto":true,"modood":true},"author":{"name":"\"Cowboy\" Ben Alman","url":"http://benalman.com/"},"repository":{"type":"git","url":"git://github.com/cowboy/javascript-hooker.git"},"versions":{"0.2.3":{"name":"hooker","description":"Monkey-patch (hook) functions for debugging and stuff.","version":"0.2.3","homepage":"http://github.com/cowboy/javascript-hooker","author":{"name":"\"Cowboy\" Ben Alman","url":"http://benalman.com/"},"repository":{"type":"git","url":"git://github.com/cowboy/javascript-hooker.git"},"bugs":{"url":"https://github.com/cowboy/javascript-hooker/issues"},"licenses":[{"type":"MIT","url":"https://github.com/cowboy/javascript-hooker/blob/master/LICENSE-MIT"}],"dependencies":{},"devDependencies":{"grunt":"~0.2.1"},"keywords":["patch","hook","function","debug","aop"],"engines":{"node":"*"},"main":"lib/hooker","scripts":{"test":"grunt test"},"_npmUser":{"name":"cowboy","email":"cowboy@rj3.net"},"_id":"hooker@0.2.3","optionalDependencies":{},"_engineSupported":true,"_npmVersion":"1.1.0-2","_nodeVersion":"v0.6.8","_defaultsLoaded":true,"dist":{"shasum":"b834f723cc4a242aa65963459df6d984c5d3d959","size":8673,"noattachment":false,"key":"/hooker/-/hooker-0.2.3.tgz","tarball":"http://registry.cnpm.dingdandao.com/hooker/download/hooker-0.2.3.tgz"},"maintainers":[{"name":"cowboy","email":""}],"directories":{},"publish_time":1328029927821,"_hasShrinkwrap":false,"_cnpm_publish_time":1328029927821}},"readme":"# JavaScript Hooker\n\nMonkey-patch (hook) functions for debugging and stuff.\n\n## Getting Started\n\nThis code should work just fine in Node.js:\n\nFirst, install the module with: `npm install hooker`\n\n```javascript\nvar hooker = require('hooker');\nhooker.hook(Math, \"max\", function() {\n  console.log(arguments.length + \" arguments passed\");\n});\nMath.max(5, 6, 7) // logs: \"3 arguments passed\", returns 7\n```\n\nOr in the browser:\n\n```html\n<script src=\"dist/ba-hooker.min.js\"></script>\n<script>\nhook(Math, \"max\", function() {\n  console.log(arguments.length + \" arguments passed\");\n});\nMath.max(5, 6, 7) // logs: \"3 arguments passed\", returns 7\n</script>\n```\n\nIn the browser, you can attach Hooker's methods to any object.\n\n```html\n<script>\nthis.exports = Bocoup.utils;\n</script>\n<script src=\"dist/ba-hooker.min.js\"></script>\n<script>\nBocoup.utils.hook(Math, \"max\", function() {\n  console.log(arguments.length + \" arguments passed\");\n});\nMath.max(5, 6, 7) // logs: \"3 arguments passed\", returns 7\n</script>\n```\n\n## Documentation\n\n### hooker.hook\nMonkey-patch (hook) one or more methods of an object.\n#### Signature:\n`hooker.hook(object, [ props, ] [options | prehookFunction])`\n#### `props`\nThe 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.\n#### `options`\n* `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.\n* `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.\n* `once` - (Boolean) if true, auto-unhook the function after the first execution.\n* `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).\n\n#### Returns:\nAn array of hooked method names.\n\n### hooker.unhook\nUn-monkey-patch (unhook) one or more methods of an object.\n#### Signature:\n`hooker.unhook(object [, props ])`\n#### `props`\nThe 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.\n#### Returns:\nAn array of unhooked method names.\n\n### hooker.orig\nGet a reference to the original method from a hooked function.\n#### Signature:\n`hooker.orig(object, props)`\n\n### hooker.override\nWhen a pre- or post-hook returns the result of this function, the value\npassed will be used in place of the original function's return value. Any\npost-hook override value will take precedence over a pre-hook override value.\n#### Signature:\n`hooker.override(value)`\n\n### hooker.preempt\nWhen a pre-hook returns the result of this function, the value passed will\nbe used in place of the original function's return value, and the original\nfunction will NOT be executed.\n#### Signature:\n`hooker.preempt(value)`\n\n### hooker.filter\nWhen a pre-hook returns the result of this function, the context and\narguments passed will be applied into the original function.\n#### Signature:\n`hooker.filter(context, arguments)`\n\n\n## Examples\nSee the unit tests for more examples.\n\n```javascript\nvar hooker = require('hooker');\n// Simple logging.\nhooker.hook(Math, \"max\", function() {\n  console.log(arguments.length + \" arguments passed\");\n});\nMath.max(5, 6, 7) // logs: \"3 arguments passed\", returns 7\n\nhooker.unhook(Math, \"max\"); // (This is assumed between all further examples)\nMath.max(5, 6, 7) // 7\n\n// Returning hooker.override(value) overrides the original value.\nhooker.hook(Math, \"max\", function() {\n  if (arguments.length === 0) {\n    return hooker.override(9000);\n  }\n});\nMath.max(5, 6, 7) // 7\nMath.max() // 9000\n\n// Auto-unhook after one execution.\nhooker.hook(Math, \"max\", {\n  once: true,\n  pre: function() {\n    console.log(\"Init something here\");\n  }\n});\nMath.max(5, 6, 7) // logs: \"Init something here\", returns 7\nMath.max(5, 6, 7) // 7\n\n// Filter `this` and arguments through a pre-hook function.\nhooker.hook(Math, \"max\", {\n  pre: function() {\n    var args = [].map.call(arguments, function(num) {\n      return num * 2;\n    });\n    return hooker.filter(this, args); // thisValue, arguments\n  }\n});\nMath.max(5, 6, 7) // 14\n\n// Modify the original function's result with a post-hook function.\nhooker.hook(Math, \"max\", {\n  post: function(result) {\n    return hooker.override(result * 100);\n  }\n});\nMath.max(5, 6, 7) // 700\n\n// Hook every Math method. Note: if Math's methods were enumerable, the second\n// argument could be omitted. Since they aren't, an array of properties to hook\n// must be explicitly passed. Non-method properties will be skipped.\n// See a more generic example here: http://bit.ly/vvJlrS\nhooker.hook(Math, Object.getOwnPropertyNames(Math), {\n  passName: true,\n  pre: function(name) {\n    console.log(\"=> Math.\" + name, [].slice.call(arguments, 1));\n  },\n  post: function(result, name) {\n    console.log(\"<= Math.\" + name, result);\n  }\n});\n\nvar result = Math.max(5, 6, 7);\n// => Math.max [ 5, 6, 7 ]\n// <= Math.max 7\nresult // 7\n\nresult = Math.ceil(3.456);\n// => Math.ceil [ 3.456 ]\n// <= Math.ceil 4\nresult // 4\n```\n\n## Contributing\nIn 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](https://github.com/cowboy/grunt).\n\n_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!_\n\n## Release History\n2012/01/09 - v0.2.3 - First official release.\n\n## License\nCopyright (c) 2012 \"Cowboy\" Ben Alman  \nLicensed under the MIT license.  \n<http://benalman.com/about/license/>\n","_attachments":{},"homepage":"http://github.com/cowboy/javascript-hooker","bugs":{"url":"https://github.com/cowboy/javascript-hooker/issues"}}