https://github.com/momsfriendlydevco/exec
Wrapper around child_process.spawn() / exec() to execute external commands
https://github.com/momsfriendlydevco/exec
Last synced: about 1 year ago
JSON representation
Wrapper around child_process.spawn() / exec() to execute external commands
- Host: GitHub
- URL: https://github.com/momsfriendlydevco/exec
- Owner: MomsFriendlyDevCo
- License: mit
- Created: 2019-04-06T05:08:20.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-11-03T05:05:50.000Z (over 3 years ago)
- Last Synced: 2025-07-18T20:20:00.527Z (about 1 year ago)
- Language: JavaScript
- Size: 94.7 KB
- Stars: 0
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
@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], , [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.