npm:superchild | Skypack

README

Superchild is a POSIX-only (e.g., Linux, Mac OS X) wrapper around node.js's built-in child_process module, which requires a lot of care and attention to use correctly.

Links:

The purpose of Superchild is to allow large node.js programs to be split into independent processes (and sub-processes, resulting in process trees), while handling the tedious parts of process management and communication.

Superchild aims to be compatible with any program that reads from and writes to their stdin, stdout, and stderr streams, regardless of what language the program is written in. This allows interesting hacks like using ssh to execute a module on a remote host, written in another language, over an encrypted link, while using the near-universal format of line-delimited JSON messages over stdio.

Features that make Superchild different from node's built-in child_process module include the following (many of these are currently possible only due to restricting focus to POSIX platforms, i.e., not Windows):

A single function to replace fork(), exec(), and spawn() from the built-in child_process module.
Waits for stdout and stderr streams to end before emitting an exit event, unlike child_process.ChildProcess.
Handles isolating child process and its children in a separate, detached process group that can be terminated as a subtree using the POSIX kill command. This means that calling close() on a Superchild instance will kill not just the child process, but all its child processes and so on (i.e., the entire process group lead by the child). Note that if any processes in the sub-tree detach themselves into a new process group, they will not be part of our child's process group, and will not be killed.
Handles graceful termination of child's entire process group using SIGTERM -> SIGKILL signals with a configurable timeout.
Handles unexpected termination of the current process by killing the child's entire process group immediately with SIGKILL.
Automatically serializes and deserializes line-delimited JSON values (LD-JSON) sent to and received from child, intermixed with stdout. stderr is passed through unbuffered. Effectively, this means that the child's stdout stream is demultiplexed into the child streams stdout_line (parsed raw text lines), json_object (parsed JSON objects), and json_array (parsed JSON arrays). Regular processes have 3 I/O streams (stdin, stdout, stderr); Superchildren have 6 streams (stdin, stdout, stderr, stdout_line, json_object, json_array).

Install

  npm install superchild

Usage

Run a shell command

Get a directory listing line-by-line using ls.

  var superchild = require('superchild');
  var child = superchild('ls -lh');
  child.on('stdout_line', function(line) {
    console.log('[stdout]: ', line);
  });

Spawn and communicate with a module

Spawn a node.js module in another process and communicate with it. Note that the child uses the superchild.unlogger helper function to parse its standard input for LD-JSON arrays and objects.

master.js

 var assert = require('assert');
 var superchild = require('superchild');
 var child = superchild('node echo.js');
 child.send({
   some: 'data',
 });
 child.on('json_object', function(jsonObj) {
   assert.equal(jsonObj.some, 'data');
 });

echo.js

 var unlogger = require('superchild').unlogger;
 unlogger().on('json_object', function(jsonObj) {
   // Echo JSON object from parent back to parent.
   console.log(JSON.stringify(jsonObj));
 });

Events emitted

Superchild is an EventEmitter. The following events can be listened for using child.on() and child.once() functions.

Event	Arguments	Description
`exit`	`code`, `signal`	Child process exited, identical to `child_process.exit`
`stderr_data`	`dataStr`	Received unbuffered data on child's `stderr` stream.
`stdout_line`	`lineStr`	Received a full line of text from the child process.
`json_object`	`jsonObj`	Parsed a line-delimited JSON object from child's `stdout` stream.
`json_array`	`jsonArr`	Parsed a line-delimited JSON array from child's `stdout` stream.

Methods

Method	Description
`send(jsonVal)`	Serialize and send a JSON-serializable object or array to the child as LD-JSON.
`close(cb)`	Gracefully terminate the child, invoking the callback when the child has died.

Requirements

node.js version 0.11.13 or higher, due to the use of spawnSync.
POSIX-compliant platform, such as Linux or Mac OS.

Source Code

The full annotated source code of superchild.js follows, generated automatically by Docco.

Helper utilities

Class JSONSieve, parses a readable stream into JSON objects and arrays, and stdout lines.
function unlogger(), an example of establishing bi-directional communication between a parent and child that can be easily ported to many other languages.

Usage no npm install needed!