spawn-wrap

What is spawn-wrap?

The spawn-wrap npm package is used to wrap child_process.spawn calls, allowing for modifications to the environment, arguments, and executable used in child processes. This is particularly useful for instrumenting child processes or modifying their behavior in a consistent way across a project.

What are spawn-wrap's main functionalities?

Environment Variable Modification

This feature allows you to prepend command line options to node processes, enabling features like harmony in all spawned child processes.

const wrap = require('spawn-wrap');
wrap(['--harmony']);
require('child_process').spawn('node', ['script.js']);

Executable Wrapping

This feature allows you to specify a custom executable (like a different version of Node.js) to be used for all child processes.

const wrap = require('spawn-wrap');
const wrappers = ['/path/to/custom/node'];
wrap(wrappers);
require('child_process').spawn('node', ['script.js']);

Other packages similar to spawn-wrap

cross-spawn

cross-spawn is similar to spawn-wrap in that it also enhances the functionality of child_process.spawn. However, cross-spawn focuses more on cross-platform compatibility, ensuring that spawned processes work similarly across different operating systems, unlike spawn-wrap which focuses on wrapping and modifying spawn calls.

forever-monitor

forever-monitor is a package that deals with managing and monitoring multiple child processes. While it provides some overlapping functionality with spawn-wrap in terms of managing child processes, its primary focus is on keeping these processes running continuously, which is different from the modification and instrumentation focus of spawn-wrap.

README

spawn-wrap

Wrap all spawned Node.js child processes by adding environs and arguments ahead of the main JavaScript file argument.

Any child processes launched by that child process will also be wrapped in a similar fashion.

This is a bit of a brutal hack, designed primarily to support code coverage reporting in cases where tests or the system under test are loaded via child processes rather than via require().

It can also be handy if you want to run your own mock executable instead of some other thing when child procs call into it.

USAGE

var wrap = require('spawn-wrap')

// wrap(wrapperArgs, environs)
var unwrap = wrap(['/path/to/my/main.js', 'foo=bar'], { FOO: 1 })

// later to undo the wrapping, you can call the returned function
unwrap()

In this example, the /path/to/my/main.js file will be used as the "main" module, whenever any Node or io.js child process is started, whether via a call to spawn or exec, whether node is invoked directly as the command or as the result of a shebang #! lookup.

In /path/to/my/main.js, you can do whatever instrumentation or environment manipulation you like. When you're done, and ready to run the "real" main.js file (ie, the one that was spawned in the first place), you can do this:

// /path/to/my/main.js
// process.argv[1] === 'foo=bar'
// and process.env.FOO === '1'

// my wrapping manipulations
setupInstrumentationOrCoverageOrWhatever()
process.on('exit', function (code) {
  storeCoverageInfoSynchronously()
})

// now run the instrumented and covered or whatever codes
require('spawn-wrap').runMain()

CAVEATS

The initial wrap call uses synchronous I/O. Probably you should not be using this script in any production environments anyway.

Also, this will slow down child process execution by a lot, since we're adding a few layers of indirection.

Currently only works on systems that support shebangs and have bash, ie, all unixes and no windows.