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(()=> /* ... */)
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
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.
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
orlog{Stdout,Stderr}
automatically implies the respectivelogStdout
/logStderr
function to be true - Setting
stdin="inherit"
is the equivelent of settingstdin=process.stdin
to connect the outer process STDIN pipe to the innner process
An object containing the default options for exec()
which can be globally changed.
Take a command line and split it into a child_process.spawn()
compatible array.
Take a disected child_process.spawn()
comaptible array and convert it into a single line, runnable shell command.