Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jcoreio/promisify-child-process
seriously like the best async child process library
https://github.com/jcoreio/promisify-child-process
async async-await child-process exec node nodejs promises spawn
Last synced: 4 days ago
JSON representation
seriously like the best async child process library
- Host: GitHub
- URL: https://github.com/jcoreio/promisify-child-process
- Owner: jcoreio
- License: mit
- Created: 2017-12-06T20:54:14.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-01-03T19:00:01.000Z (18 days ago)
- Last Synced: 2025-01-07T04:39:58.828Z (14 days ago)
- Topics: async, async-await, child-process, exec, node, nodejs, promises, spawn
- Language: JavaScript
- Size: 1.09 MB
- Stars: 64
- Watchers: 5
- Forks: 3
- Open Issues: 44
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# promisify-child-process
[](https://circleci.com/gh/jcoreio/promisify-child-process)
[](https://codecov.io/gh/jcoreio/promisify-child-process)
[](https://github.com/semantic-release/semantic-release)
[](http://commitizen.github.io/cz-cli/)
[](https://badge.fury.io/js/promisify-child-process)
seriously like the best async child process library
(I'm joking, you may want to use [`execa`](https://github.com/sindresorhus/execa) which has a lot more features. The minor advantages of this package are,
it's a dual CJS/ESM package, and it provides wrappers for all the async `child_process` functions.)
Based upon [`child-process-async`](https://github.com/itsjustcon/node-child-process-async),
but more thorough, because that package doesn't seem very actively maintained.
`promisify-child-process` provides a **drop-in replacement** for the
original `child_process` functions, not just duplicate methods that
return a `Promise`. So when you call `exec(...)` we still return a
`ChildProcess` instance, just with `.then()`, `.catch()`, and `.finally()` added to
make it promise-friendly.
## Install and Set-up
```sh
npm install --save promisify-child-process
```
If you are using a old version of Node without built-in `Promise`s or
`Object.create`, you will need to use polyfills (e.g. `@babel/polyfill`).
```js
// OLD:
const { exec, spawn, fork, execFile } = require('child_process')
// NEW:
const { exec, spawn, fork, execFile } = require('promisify-child-process')
```
## Upgrading to v3
You must now pass `maxBuffer` or `encoding` to `spawn`/`fork` if you want to
capture `stdout` or `stderr`.
## Resolution/Rejection
The child process promise will only resolve if the process exits with a code of 0.
If it exits with any other code, is killed by a signal, or emits an `'error'` event,
the promise will reject.
## Capturing output
`exec` and `execFile` capture `stdout` and `stderr` by default. But `spawn` and
`fork` don't capture `stdout` and `stderr` unless you pass an `encoding` or
`maxBuffer` option:
```js
const { spawn } = require('promisify-child-process');
async function() {
// captures output
const { stdout, stderr } = await spawn('ls', [ '-al' ], {encoding: 'utf8'});
const { stdout, stderr } = await spawn('ls', [ '-al' ], {maxBuffer: 200 * 1024});
// BUG, DOESN'T CAPTURE OUTPUT:
const { stdout, stderr } = await spawn('ls', [ '-al' ]);
}
```
## Additional properties on rejection errors
If the child process promise rejects, the error may have the following additional
properties:
- `code` - the process' exit code (if it exited)
- `signal` - the signal the process was killed with (if it was killed)
- `stdout` - the captured `stdout` (if output capturing was enabled)
- `stderr` - the captured `stderr` (if output capturing was enabled)
## Wrapper
If for any reason you need to wrap a `ChildProcess` you didn't create,
you can use the exported `promisifyChildProcess` function:
```js
const { promisifyChildProcess } = require('promisify-child-process');
async function() {
const { stdout, stderr } = await promisifyChildProcess(
some3rdPartyFunctionThatReturnsChildProcess(),
{ encoding: 'utf8' }
)
}
```
## Examples
### `exec()`
```js
async function() {
const { stdout, stderr } = await exec('ls -al');
// OR:
const child = exec('ls -al', {});
// do whatever you want with `child` here - it's a ChildProcess instance just
// with promise-friendly `.then()` & `.catch()` functions added to it!
child.stdin.write(...);
child.stdout.pipe(...);
child.stderr.on('data', (data) => ...);
const { stdout, stderr } = await child;
}
```
### `spawn()`
```js
async function() {
const { stdout, stderr, code } = await spawn('ls', [ '-al' ], {encoding: 'utf8'});
// OR:
const child = spawn('ls', [ '-al' ], {});
// do whatever you want with `child` here - it's a ChildProcess instance just
// with promise-friendly `.then()` & `.catch()` functions added to it!
child.stdin.write(...);
child.stdout.pipe(...);
child.stderr.on('data', (data) => ...);
const { stdout, stderr, code } = await child;
}
```