README

single-child

Spawn a single child process which kills itself on restart.

This was built as a module of listen-spawn, a CLI tool that starts a web-server and runs a command every time it is pinged. Think of it as a nodemon over HTTP.

Getting Started

Install the module with: npm install single-child

// Create a new child which starts my app
var SingleChild = require('single-child'),
    child = new SingleChild('npm', ['start'], {stdio: [0,1,2]});

// Start my child (and hence my app)
child.start();

// Restart my app every 10 seconds
setInterval(function () {
  child.restart();
}, 10000);

Documentation

SingleChild acts as a constructor and accepts the same parameters as child_process#spawn with a few extras.

new SingleChild(cmd, [args], [options]);
/**
 * Spawn for a single child. Always guarantees only one child exists
 * @see child_process.spawn
 * @param {String} cmd Command to run
 * @param {String[]} [args] Array of arguments to pass with cmd
 * @param {Object} [options] Options to pass to `spawn` and for ourselves
 * @param {Mixed} [options.killSignal] Signal to pass to `kill` executions
 */

Methods

SingleChild#start and SingleChild#restart are how we start children. These are aliases.

child.start([cb]);
child.restart([cb]);
/**
 * Stop the currently running child and start a new one
 * @param {Function} [cb] Error-first callback that returns *before* the child starts
 * @callback {Error|Null} err Error if there was one
 * @callback {ChildProcess} child Child that was started. Generated by node's child_process#spawn
 */

SingleChild#stop and SingleChild#kill are how we stop children. stop invokes kill with SIGINT rather than allowing for input.

child.stop([cb]);
child.kill([options], [cb]);
/**
 * Stop the currently running program
 * @param {Object} [options] Options for the kill action
 * @param {Mixed} [options.signal] Signal to use when killing
 * @param {Function} [cb] Callback to run when process has been killed.
 *     Receives same params as node's ChildProcess#close event
 */

Events

SingleChild fires the following events over its lifecycle:

starting() is run before a child is spawned
started() is run after a child is spawned (does not mean process is running)
exited(code, signal) is run when a child exits
killing() is run before a child is killed
killed() is run after a child is killed

Examples

A watered down listen-spawn example:

// Create a new child which starts my app
var SingleChild = require('single-child'),
    child = new SingleChild('npm', ['start'], {stdio: [0,1,2]});

// Start my child (and hence my app)
child.start();

// Notify user on start and exit events
child.on('started', function () {
  console.log('App started!');
});
child.on('exited', function () {
  console.log('App exited!');
});

// Begin a server which restarts the app when hit
var http = require('http');
http.createServer(function (req, res) {
  // We received a ping, restart the server
  child.restart();

  // Send a NO CONTENT response
  res.write(204);
  res.close();
}).listen(3000);

// Notify the user the server is up
console.log('Server is listening at http://localhost:3000/');

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via grunt and test via npm test.

License

Licensed under the MIT license.

Usage no npm install needed!