@momsfriendlydevco/exec

1.5.9 • Public • Published

@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.

Package Sidebar

Install

npm i @momsfriendlydevco/exec

Weekly Downloads

1

Version

1.5.9

License

MIT

Unpacked Size

21 kB

Total Files

4

Last publish

Collaborators

  • hash-bang
  • 1watt
  • eekthecat
  • melromero
  • mr-yellow