API Docs for: 0.3.0
Show:

Hook Class

Defined in: lib/hook.js:6
Module: main

provides a mechanism to transform code in the scope of require or vm.createScript. 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.

For the common case of matching filesystem paths based on inclusion/ exclusion patterns, use the matcherFor function in the istanbul API to get a matcher.

It is up to the transformer to perform processing with side-effects, such as caching, storing the original source code to disk in case of dynamically generated scripts etc. The Store class can help you with this.

Usage

 var hook = require('istanbul').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

Item Index

Methods

Methods

hookCreateScript

(
  • matcher
  • transformer
  • options
)
static

Defined in lib/hook.js:117

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.

    • [verbose] Boolean optional

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

hookRequire

(
  • matcher
  • transformer
  • options
)
static

Defined in lib/hook.js:77

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.

    • [verbose] Boolean optional

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

    • [postLoadHook] Function optional

      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
  • options
)
static

Defined in lib/hook.js:148

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.

  • options Object

    options Optional.

    • [verbose] Boolean optional

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

unhookCreateScript

() static

Defined in lib/hook.js:138

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

unhookRequire

() static

Defined in lib/hook.js:109

unhook require to restore it to its original state.

unhookRunInThisContext

() static

Defined in lib/hook.js:168

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