@momsfriendlydevco/exec

Tiny wrapper around child_process.spawn() / exec() which provides some additional functionality.

Differences from spawn / exec:

Always returns a promise for running processes. That promise can return output if buffer is enabled
Can easily prefix output to STDOUT / STDERR or both
Can accept a single array of command arguments rather than treating the program + args separately
Can accept a single string command which is correctly transformed internally
Optionally can buffer and provide all output when resolving / rejecting
Supports piping
Auto-trimming out output
Hashbangs supported
Can natively accept JSON and fail if not given valid input
Support for aliases within commands (and pipes)

var exec = require('@momsfriendlydevco/exec');

exec('echo "Hello world"')
	.then(()=> /* ... */)

exec(['docker', 'build', '--tag=momsfriendlydevco/test', '.'], {
	prefix: '[docker]',
})
	.then(()=> /* ... */)

Debugging

This module uses the Debug NPM package and responds to exec.

To see verbose debugging output simply set DEBUG=exec or any valid glob expression.

> DEBUG=exec node someNodeFile.js

API

This module exposes a function (which returns a promise) as well as a few utility functions. The function takes an array (or string) of arguments where the executable is the first item within that array. An additional options object can be passed.

exec([cmd], <cmd+args|args>, [options])

Supported options:

Option	Type	Default	Description
`buffer`	`boolean`	`undefined`	Set both `bufferStdout` + `bufferStderr` at once
`bufferStdout`	`boolean`	`false`	When resolving the promise provide the output from the command as the value of the resolved promise
`bufferStderr`	`boolean`	`false`	As with `bufferStdout` but also include STDERR stream data
`log`	`boolean` or `function`	`undefined`	Set both `logStdout` + `logStderr` at once
`logStdout`	`boolean` or `function`	`console.log`	Logging function to use when outputting STDOUT, set to falsy to disable
`logStderr`	`boolean` or `function`	`console.log`	Similar to `logStdout` but with the STDERR stream
`prefix`	`string` or `function`	`undefined`	Sets both `prefixStdout` + `prefixStderr` at once
`prefixStdout`	`string` or `function`	`undefined`	Sets a string prefix for any STDOUT output, if a function it is called as `(msg)` and uses the return value, effectively acting as a wrapper
`prefixStderr`	`string` or `function`	`undefined`	Similar functionality to `prefixStdout` but with STDERR streams
`rejectError`	`string`, `boolean` or `function`	`'Non-zero exit code'`	If a string use this to signal errors, boolean `false` returns the error code in the `catch()` block, if a function that function is called as `(code)` to return the string to return
`reformat`	`boolean`	`undefined`	Set both `reformatStdout` + `reformatStderr` at once
`reformatStdout`	`boolean`	`false`	When accepting data from Stdout and `prefixStdout` is enabled, also split newline input so each newline is prefixed
`reformatStderr`	`boolean`	`false`	As with `reformatStdout` but also reformat STDERR stream data
`resolveCodes`	`array`	`[0]`	Array of numeric error codes to accept as a valid response
`json`	`boolean`	`false`	Attempt to convert the contents of the output buffer (contents dictated by `buffer*` into JSON before returning
`jsonInvalidTruncate`	`number`	`30`	When parsing invalid JSON truncate the error output to this many bytes (i.e. not UTF-8 friendly)
`jsonInvalidTruncateSuffix`	`string`	`"…"`	Suffix to append when truncating invalid JSON input
`pipe`	`boolean` or `string`	`'auto'`	Use the shell to execute, if `'auto'` pipes are detected automatically
`shell`	`string`	`'/bin/sh'`	A STDIN processing shell, used when `pipe` is true or auto detected
`hashbang`	`boolean`	`true`	If specified the file is opened and `hashbangReadLength` bytes examined for a hashbang, if one is found the command is prefixed with it
`hashbangReadLength`	`number`	`100`	How many bytes to explore at the start of files for the hashbang
`trim`	`boolean`	`true`	Automatically trim output to remove trailing newlines and spaces
`trimRegExp`	`RegExp`	`/[\n\s]+$/m`	The regular expression used when trimming
`env`	`object`	`{}`	Environment variables to pass to the shell
`cwd`	`string`	`undeinfed`	The current working directory to execute the process within
`uid`	`number`	`undefined`	The UID who owns the process
`gid`	`number`	`undefined`	The GID who owns the process
`alias`	`object`	`{}`	Object list of command aliases
`stdin`	`stream.Readable`, `"inherit"`, `buffer` or `string`	`undefined`	Either connect the stream to the proess STDIN or feed the given input into STDIN if its a string or buffer

NOTES:

Setting log or log{Stdout,Stderr} automatically implies the respective logStdout / logStderr function to be true
Setting stdin="inherit" is the equivelent of setting stdin=process.stdin to connect the outer process STDIN pipe to the innner process

exec.defaults

An object containing the default options for exec() which can be globally changed.

exec.split(cmd)

Take a command line and split it into a child_process.spawn() compatible array.

exec.join(args)

Take a disected child_process.spawn() comaptible array and convert it into a single line, runnable shell command.

Current Tags

1.5.2 ... latest (10 months ago)