adept-spawn v1.0.0

adept-spawn

Install

npm install adept-spawn

Contents

• Usage
• The exports
• The factories
  • createSpawn(originalSpawn)
  • spawn like function
    • The template syntax
    • options, and defaults
• The object returned by spawn
  • ChildProcessWrapper()
  • streams
  • c.pipeTo(dest)
• About

Usage

const { spawn } = require('adept-spawn');
//import { spawn } from 'adept-spawn';

//A command and arguments are a string.
const c = spawn(`ls %(quote)`, {
    //Use string formatting
    quote: '-Q'
}, {
    //The options for require('child_process').spawn
    stdio: [process.stdin, 'pipe', process.stderr]
});

console.log('current pid is ', c.pid);
let n = 0;
//stdout, stdin, and stderr return highland streams
c.stdout.split('\n').each(function(x){
    console.log(`file ${++n}`, x);
});

Maybe normal spawn isn't enough for you. For example cross-spawn will work better for all platforms.

const { createSpawn } = require('adept-spawn');
const crossSpawn = require('cross-spawn');
//import { createSpawn } from 'adept-spawn';
//import crossSpawn from 'cross-spawn';
const spawn = createSpawn(crossSpawn);

spawn(`ls`);

The exports

//spawn, and fork are created by passing
//spawn, and fork from 'child_process' module
//to createSpawn
const {
    spawn,
    fork,
    createSpawn
} = require('adept-spawn');

The factories

createSpawn(originalSpawn)

originalSpawn should be a spawn, fork, or some spawn like function that conforms to the interface of spawn from the child_process spawn module.

createSpawn() returns a spawn like function.

spawn like function

A spawn like function should work mostly like require('child_process').spawn. There are some major differences.

The normal spawn() has this interface:

spawn(command, args, options, defaults)

The spawn like function has this interface:

spawn(input, format, options, defaults)

The input argument is a cli command that works similar to require('child_process').exec.

The input argument also has a template syntax 'ls %(somePropertyName)'. The format argument should be an object that gets it's property values inserted into the input template syntax.

The template syntax

Using %(property) in a string does template interpolation on the format object. Use \\%() to escape the template syntax.

options, and defaults

The options, and defaults arguments are the same as regular child_process spawn.

The object returned by spawn

ChildProcessWrapper()

ChildProcessWrapper() instances wrap a child process returned by a spawn that's wrapped by createSpawn().

//c = new ChildProcessWrapper(child_process);
const c = spawn('ls');

ChildProcessWrapper() instances have all the properties, and functions as a regular child process plus some extras.

streams

c.stdout, c.stdin, and c.stderr each return a highland stream.

c.pipeTo(dest)

Pipe to stdout to a stream, or name a file to pipe to.

const { spawn } = require('adept-spawn');
const fs = require('fs');

const c = spawn('ls');
c.pipeTo('filename');

Or create a stream manually.

c.pipeTo(fs.createWriteStream('filename'));

About

adept-spawn tries to be a little more helpful than just regular child_process spawn, and child_process fork.