extra-child-process

Useful additions to inbuilt child_process module.
📦 Node.js, 📜 Files, 📰 Docs.

Have you heard of bash or command prompt? These programs are called shells. They watch what you type, and treat it as requests to run particular programs. Programs themselves are just names on the file system, and the shell searches them in a particular manner (controlled with environment variables such as PATH). Our programs as based on UNIX principles, where each program can accept an initial input through arguments, runtime input through stdin input stream #0, and provide its runtime output into stdout output stream #1 (along with stderr output stream #2 for errors). The output of a program can be fed into another program through piping |, allowing us to set up a pipline of programs to achieve a complex operation (without having to write a new program).

child_process is an inbuilt Node.js module that enables us to execute specific programs directly (execFile), or through the shell (exec). Executing programs through the shell is hyper convenient as we are allowed to use its inbuilt commands and features such as piping of streams, but is does come with a security risk (such as command injection) when using unsanitized user input to generate the sequence of instructions to be executed on the shell. When possible, execting specific programs directly using execFile would be a suitable approach. spawn can be used when we want to start a new process and control its input and output streams. exec and execFile are implemented on top of spawn. fork is a special case of spawn, used specifically to launch new Node.js processes.

This package provides async versions of functions (in additon to the existing sync and callback-based functions), which are not included with the inbuilt child_process module. They are named as *Async can be used with Promise-based asynchronous programming using the await keyword. spawnAsync is a special case here, which returns a PromiseWithChild which is essentially a Promise with a .child property to allow ChildProcess to be directly accessed similar to spawn. In addition, callback-based functions, such as exec, also behave as async functions when a callback is not provided. Functions for locating path of executable(s) such as which and whichAll are also included. Design was based on local ideas and literature survey.

Stability: Experimental.

const xcp = require('extra-child-process');


// 1. List files in current directory.
async function example1() {
  var {stdout, stderr} = await xcp.exec('ls -a');
  var {stdout, stderr} = await xcp.execFile('ls', ['-a']);
  xcp.exec('ls -a', (err, stdout, stderr) => 0);
  xcp.execFile('ls', ['-a'], (err, stdout, stderr) => 0);
  // → .
  // → ..
  // → .build
  // → .git
  // → .github
  // → ...
}
example1();


// 2. List files in 'src' directory.
async function example2() {
  var {stdout, stderr} = await xcp.exec('ls -a', {cwd: 'src'});
  var {stdout, stderr} = await xcp.execFile('ls', ['-a'], {cwd: 'src'});
  xcp.exec('ls -a', {cwd: 'src'}, (err, stdout, stderr) => 0);
  xcp.execFile('ls', ['-a'], {cwd: 'src'}, (err, stdout, stderr) => 0);
  // → .
  // → ..
  // → index.ts
}
example2();


// 3. Locate path of node executable.
async function example3() {
  var paths = process.env.PATH.split(';');
  var exec  = await xcp.which('node');
  var exec  = await xcp.which('node', {paths});
  // → 'D:\\Program Files\\nodejs\\node.exe'
}
example3();


// 4. Locate path of n*e executables.
async function example4() {
  var paths = process.env.PATH.split(';');
  var execs = await xcp.whichAll(/^n.*?e$/);
  var execs = await xcp.whichAll(/^n.*?e$/, {paths});
  // → [
  // →   'D:\\Program Files\\Git\\usr\\bin\\nice.exe',
  // →   'C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v11.2\\bin\\nvprune.exe',
  // →   'D:\\Program Files\\nodejs\\node.exe'
  // → ]
}
example4();

Index

Property	Description
exec	Execute a command within a shell, buffering any output.
execFile	Execute an executable without a shell by default, buffering any output.
fork	This method is a special case of spawn used specifically to spawn new Node.js processes.
spawn	This method spawns a new process using the given `command` and `args`.
spawnAsync	Spawn new process using given command and arguments.
which	Locate path of executable for given command.
whichAll	Locate paths of all matching executables for given command.