@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), implies bufferStdout
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.