npm package: @momsfriendlydevco/exec
Description: Wrapper around child_process.spawn() / exec() to execute external commands
Author: Matt Carter
Latest version: 1.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)


```javascript
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](https://github.com/visionmedia/debug#readme) 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.