Provides a hooking mechanism for Node.js require() calls
npm install require-hacker
Is a small helper module providing tools for instrumenting Node.js require() calls.
- What it does and why is it needed?
- Installation
- Usage
- Configuration
- API
- Gotchas
- References
- Contributing
Standard Node.js require() calls simply loaded javascript files from disk and evaluated them.
Some time after various hackers hacked the Module module and various solutions emerged such as coffee-script/register and babel-core/register allowing everyone to require() code written in any language out there (coffeescript and ES7 in case of the aforementioned "require hooks").
This module provides a tool to perform such tricks along with a possibility to also intercept require() calls not just for specific file extensions but for an arbitrary abstract path. Consider, for example, require("http://thor.onion/module?user=123") or require("春秋左傳·僖公二十二年"), whatever. Who might need this? You never know.
``bash`
$ npm install require-hacker --save
Something basic
`javascript
import require_hacker from 'require-hacker'
import fs from 'fs'
// mount require() hook
const hook = require_hacker.hook('txt', path =>
{
return module.exports = "${fs.readFileSync(path).replace(/"/g, '\"')}"
})
// will output text file contents
console.log(require('./test.txt'))
// unmount require() hook
hook.unmount()
// will throw "SyntaxError: Unexpected token ILLEGAL"
require('./test without hook.txt')
`
Something unusual
`javascript
const hook = require_hacker.global_hook('network', path =>
{
if (!path.starts_with('http://xhamster.com'))
{
return
}
// returns javascript module source code, something like:
//
// "module.exports =
// {
// category : 'redhead',
// videos : [12345, 12346, 12347],
// unsubscribe: function()
// {
// http.post('http://xhamster.com/unsubscribe', { user: 123 })
// }
// }"
//
const source = synchronous_http.get(path)
return { source, path }
})
const readheads = require('http://xhamster.com/category/redhead')
readheads.unsubscribe()
`
Or
`javascript
const hook = require_hacker.global_hook('database', path =>
{
if (!path.starts_with('postgresql://'))
{
return
}
// returns javascript module source code, something like:
//
// "module.exports =
// {
// words: ['a', 'b', 'c']
// sum: function()
// {
// return words.join('')
// }
// }"
//
const schema = path.substring(0, 'postgresql://'.length)
const source pg.sql(select * from ${schema}.generate_javascript())
return { source, path }
})
const summator = require('postgresql://summator')
console.log(summator.sum())
`
And don't ask me what for.
To see debug logs in the console one can use this code
`javascript`
require_hacker.log.options.debug = true
#### .hook(file_extension, resolve)
Will intercept all require() calls for paths with this file_extension and reroute them to the resolve function. The require()d path must exist in the filesystem, otherwise an exception will be thrown: Cannot find module.
Returns an object with .unmount() method which unmounts this require() hook from the system.
The resolve function takes two parameters:
* the path which is require()dmodule
* the in which the require() call was originated (this module parameter can be used for require_hacker.resolve(path, module) function call)
The resolve function must return either a valid CommonJS javascript module source code (i.e. "module.exports = ...", etc) or it can simply return nothing and in that case it will skip this hook.
#### .global_hook(meaningful_id, resolve, [options])
Can intercept all require() calls. The behaviour is controlled by precede_node_loader option:
* when it's true (default) it will intercept all require() calls before they are passed to the original Node.js require() loaderfalse
* when it's it will intercept only those require() calls which failed to be resolved by the original Node.js require() loader
Returns an object with .unmount() method which unmounts this require() hook from the system.
The resolve function takes two parameters:
* the path which is require()d (e.g. a relative one)module
* the in which the require() call was originated (this module parameter can be used for require_hacker.resolve(path, module) function call)
The resolve function must return either undefined (in which case it will skip this hook and proceed as normal) or an object { source, path } where
* source is a valid CommonJS javascript module source code (i.e. "module.exports = ...", etc)path
* is the absolute path of the path argument passed to this require() function (which could be relative). This returned path is only gonna matter if require()ing some other relative path from the source being returned (because it would get resolved against this absolute path).
#### .resolver(resolve)
Can intercept all require(path) calls and tamper with the path modifying it if needed (this process is called "resolving").
Returns an object with .unmount() method which unmounts this interceptor.
The resolve function takes two parameters:
* the path which is require()d.module
* the in which the require() call was originated (this module parameter can be used for require_hacker.resolve(path, module) function call)
The resolve function must either return a real filesystem path to a javascript (or json) file or it can simply return nothing and in that case it will take no effect.
#### .to_javascript_module_source(anything)
Converts anyting (an undefined, a string, a JSON object, a function, a regular expression - anything) to a valid CommonJS javascript module source code.
#### .resolve(path, module)
Resolves a requireable path to a real filesystem path to a javascript (or json) file. Resolution is performed relative to the module (javascript file) passed as the second parameter (resolves npm link, global node_modules, etc). It's just an alias to the native Node.js path resolution function. Will throw Error: Cannot find module '...' if the path isn't resolved to an existing javascript (or json) file.
None whatsoever
There are various articles on this sort of require() hook trickery on the internets.
Hooking into Node loader for fun and profit
After cloning this repo, ensure dependencies are installed by running:
`sh`
npm install
This module is written in ES6 and uses Babel for ES5
transpilation. Widely consumable JavaScript can be produced by running:
`sh`
npm run build
Once npm run build has run, you may import or require() directly from
node.
After developing, the full test suite can be evaluated by running:
`sh`
npm test
When you're ready to test your new functionality on a real project, you can run
`sh`
npm pack
It will build, test and then create a .tgz archive which you can then install in your project folder
`sh``
npm install [module name with version].tar.gz