# @momsfriendlydevco/exec > Wrapper around child_process.spawn() / exec() to execute external commands Latest version **1.5.9** (published 2022-11-03) · MIT license · 0 weekly downloads ## Install ```sh npm install @momsfriendlydevco/exec pnpm add @momsfriendlydevco/exec yarn add @momsfriendlydevco/exec bun add @momsfriendlydevco/exec ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.5.9 | | Published | 2022-11-03 | | First published | 2019-04-07 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=14.15.0 | | Dependencies | 2 | | Unpacked size | 20.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Author | Matt Carter | | Maintainers | hash-bang, 1watt, eekthecat, melromero, mr-yellow | | Keywords | child_process, exec, spawn | ## Links - npm: https://www.npmjs.com/package/@momsfriendlydevco/exec - Repository: https://github.com/MomsFriendlyDevCo/exec - Homepage: https://github.com/MomsFriendlyDevCo/exec#readme - Issues: https://github.com/MomsFriendlyDevCo/exec/issues - npm.io page: https://npm.io/package/@momsfriendlydevco/exec ## Dependencies (2) - [debug](https://npm.io/package/debug.md) ^4.3.2 - [spawn-args](https://npm.io/package/spawn-args.md) ^0.2.0 ## Recent versions - 1.5.9 (latest) — 2022-11-03 - 1.5.8 — 2021-09-13 - 1.5.7 — 2021-08-30 - 1.5.6 — 2021-05-31 - 1.5.5 — 2021-05-23 - 1.5.4 — 2021-05-23 - 1.5.3 — 2021-05-23 - 1.5.2 — 2020-03-12 - 1.5.1 — 2020-03-12 - 1.5.0 — 2019-10-18 - 1.4.3 — 2019-07-21 - 1.4.2 — 2019-07-21 - 1.4.1 — 2019-07-21 - 1.4.0 — 2019-07-18 - 1.3.0 — 2019-04-16 - … 8 more at https://npm.io/package/@momsfriendlydevco/exec/versions ## 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. --- _Source: https://npm.io/package/@momsfriendlydevco/exec · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._