Exports

istanbul-lib-hook provides mechanisms to transform code in the scope of require, vm.createScript, vm.runInThisContext etc.

This mechanism is general and relies on a user-supplied matcher function that determines when transformations should be performed and a user-supplied transformer function that performs the actual transform. Instrumenting code for coverage is one specific example of useful hooking.

Note that both the matcher and transformer must execute synchronously.

Examples

var hook = require('istanbul-lib-hook'),
    myMatcher = function (file) { return file.match(/foo/); },
    myTransformer = function (code, file) {
        return 'console.log("' + file + '");' + code;
    };

hook.hookRequire(myMatcher, myTransformer);
var foo = require('foo'); //will now print foo's module path to console

hookCreateScript(matcher, transformer, options, opts)

hooks vm.createScript to return transformed code out of which a Script object will be created. Exceptions in the transform result in the original code being used instead.

Parameters

• matcher :

  {Function(filePath)} a function that is called with the filename passed to vm.createScript Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise

• transformer :

  {Function(code, filePath)} a function called with the original code and the filename passed to vm.createScript. Should return the transformed code.

• options :

  {Object} options Optional.

• [Boolean] options.verbose

  write a line to standard error every time the transformer is called

• opts :

hookRequire(matcher, transformer, options)

hooks require to return transformed code to the node module loader. Exceptions in the transform result in the original code being used instead.

Parameters

• matcher :

  {Function(filePath)} a function that is called with the absolute path to the file being require-d. Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise

• transformer :

  {Function(code, filePath)} a function called with the original code and the associated path of the file from where the code was loaded. Should return the transformed code.

• options :

  {Object} options Optional.

• [Boolean] options.verbose

  write a line to standard error every time the transformer is called

• [Function] options.postLoadHook

  a function that is called with the name of the file being required. This is called after the require is processed irrespective of whether it was transformed.

hookRunInThisContext(matcher, transformer, opts)

hooks vm.runInThisContext to return transformed code.

Parameters

• matcher :

  {Function(filePath)} a function that is called with the filename passed to vm.createScript Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise

• transformer :

  {Function(code, filePath)} a function called with the original code and the filename passed to vm.createScript. Should return the transformed code.

• opts :

  {Object} [opts={}] options

• [Boolean] opts.verbose

  write a line to standard error every time the transformer is called

unhookCreateScript

unhooks vm.createScript, restoring it to its original state.

unhookRequire

unhook require to restore it to its original state.

unhookRunInThisContext

unhooks vm.runInThisContext, restoring it to its original state.

unloadRequireCache(matcher)

unloads the required caches, removing all files that would have matched the supplied matcher.

Parameters

• Function matcher :

  the match function that accepts a file name and returns if that file should be unloaded from the cache.