single-child

Spawn a single child process which kills itself on restart

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.

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);

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
 */

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
 */

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

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 (reqres) {
  // 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/');

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.

Copyright (c) 2013 Todd Wolfson

Licensed under the MIT license.