@momsfriendlydevco/exec v1.5.9
@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
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
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.
1 year ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago