# spawncommand

> Spawn or fork a child process with a promise property resolved on exit with stdout, stderr and code.

Latest version **2.2.0** (published 2019-04-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install spawncommand
pnpm add spawncommand
yarn add spawncommand
bun add spawncommand
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2019-04-25 |
| First published | 2017-02-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 17.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | anton |
| Maintainers | zvr |
| Keywords | spawn, fork, async, child_process, child process, ChildProcess, promise, stdout, stderr, stdio |

## Links

- npm: https://www.npmjs.com/package/spawncommand
- Repository: https://github.com/artdecocode/spawncommand
- Homepage: https://github.com/artdecocode/spawncommand#readme
- Issues: https://github.com/artdecocode/spawncommand/issues
- npm.io page: https://npm.io/package/spawncommand

## Dependencies (1)

- [catchment](https://npm.io/package/catchment.md) ^3.3.0

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 2.2.0 (latest) — 2019-04-25
- 2.1.2 — 2019-04-04
- 2.1.1 — 2019-03-11
- 2.1.0 — 2018-09-20
- 2.0.1 — 2018-05-17
- 2.0.0 — 2018-05-14
- 1.1.0 — 2017-04-18
- 1.0.1 — 2017-02-04

## README

# spawnCommand

[![npm version](https://badge.fury.io/js/spawncommand.svg)](https://npmjs.org/package/spawncommand)

_SpawnCommand_ will run the `spawn` or `fork` methods from the `child_process` module, and add a `promise` property to the returned process instance. The promise will be resolved on process exit with an object consisting of `code`, `stdout` and `stderr` properties.

```
yarn add spawncommand
```

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/0.svg?sanitize=true"></a></p>

## Table Of Contents

- [Table Of Contents](#table-of-contents)
- [API](#api)
  * [Types](#types)
    * [`_spawncommand.ChildProcessWithPromise`](#type-_spawncommandchildprocesswithpromise)
    * [`_spawncommand.PromiseResult`](#type-_spawncommandpromiseresult)
  * [`spawn(module: string, args: string[], options?: SpawnOptions): ChildProcessWithPromise`](#spawnmodule-stringargs-stringoptions-spawnoptions-childprocesswithpromise)
  * [`fork(module: string, args: string[], options?: ForkOptions): ChildProcessWithPromise`](#forkmodule-stringargs-stringoptions-forkoptions-childprocesswithpromise)
- [Copyright](#copyright)

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/1.svg?sanitize=true"></a></p>

## API

_SpawnCommand_ can be used by importing the default `spawn` and named `fork` exports.

```js
import spawn, { fork } from 'spawncommand'
```

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/2.svg?sanitize=true" width="15"></a></p>

### Types

The package's main type is _ChildProcessWithPromise_ which enriches the standard _ChildProcess_ with a `promise` property.

[`import('child_process').ChildProcess`](https://nodejs.org/api/child_process.html#child_process_class_childprocess) __<a name="type-child_processchildprocess">`child_process.ChildProcess`</a>__

__<a name="type-_spawncommandchildprocesswithpromise">`_spawncommand.ChildProcessWithPromise`</a>__: A child process with an extra `promise` property.

|       Name        |                         Type                          |                Description                 |
| ----------------- | ----------------------------------------------------- | ------------------------------------------ |
| __promise*__      | <em>!Promise&lt;!_spawncommand.PromiseResult&gt;</em> | A promise resolved when the process exits. |
| __spawnCommand*__ | <em>string</em>                                       | The spawn arguments joined by whitespace.  |

__<a name="type-_spawncommandpromiseresult">`_spawncommand.PromiseResult`</a>__

|    Name     |      Type       |                  Description                   |
| ----------- | --------------- | ---------------------------------------------- |
| __stdout*__ | <em>string</em> | The accumulated result of the `stdout` stream. |
| __stderr*__ | <em>string</em> | The accumulated result of the `stderr` stream. |
| __code*__   | <em>number</em> | The code with which the process exited.        |

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/3.svg?sanitize=true" width="15"></a></p>

### `spawn(`<br/>&nbsp;&nbsp;`module: string,`<br/>&nbsp;&nbsp;`args: string[],`<br/>&nbsp;&nbsp;`options?: SpawnOptions,`<br/>`): ChildProcessWithPromise`

Spawns a command and returns a _ChildProcess_ instance with the `promise` property resolved on exit. The promise will be rejected if an error was encountered when trying to spawn the process.

`import('child_process').SpawnOptions` __<a name="type-child_processspawnoptions">`child_process.SpawnOptions`</a>__

```js
import spawn from 'spawncommand'

(async () => {
  const { promise } = spawn('echo', ['hello world'])
  const { stderr, stdout, code } =  await promise
  console.log(JSON.stringify({
    stderr, stdout, code,
  }, null, 2))
})()
```
```json5
{
  "stderr": "",
  "stdout": "hello world\n",
  "code": 0
}
```

The returned object is a `ChildProcess` and all of its properties can be accessed in the standard way.

```js
import spawnCommand from 'spawncommand'

(async () => {
  const { stdout, promise } = spawnCommand('echo', ['hello world'])

  stdout.pipe(process.stdout)
  await promise
})()
```
```
hello world
```

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/4.svg?sanitize=true" width="15"></a></p>

### `fork(`<br/>&nbsp;&nbsp;`module: string,`<br/>&nbsp;&nbsp;`args: string[],`<br/>&nbsp;&nbsp;`options?: ForkOptions,`<br/>`): ChildProcessWithPromise`

Forks a Node.js module and adds a `promise` property to the returned _ChildProcess_.

`import('child_process').ForkOptions` __<a name="type-child_processforkoptions">`child_process.ForkOptions`</a>__

```js
import { fork } from 'spawncommand'

(async () => {
  const { promise } = fork('node_modules/.bin/alanode',
    ['example/spawn.js'], {
      stdio: 'pipe',
    })
  const { stdout } =  await promise
  console.log(stdout)
})()
```
```json5
{
  "stderr": "",
  "stdout": "hello world\n",
  "code": 0
}
```

The `pipe` option needs to be set in order to gather the output of the `stderr` and `stdout` streams (or an array for older versions of Node.js when [this does not work][2]).

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/5.svg?sanitize=true"></a></p>

## Copyright

<table>
  <tr>
    <th>
      <a href="https://artd.eco">
        <img src="https://raw.githubusercontent.com/wrote/wrote/master/images/artdeco.png" alt="Art Deco" />
      </a>
    </th>
    <th>© <a href="https://artd.eco">Art Deco</a>   2019</th>
    <th>
      <a href="https://www.technation.sucks" title="Tech Nation Visa">
        <img src="https://raw.githubusercontent.com/artdecoweb/www.technation.sucks/master/anim.gif"
          alt="Tech Nation Visa" />
      </a>
    </th>
    <th><a href="https://www.technation.sucks">Tech Nation Visa Sucks</a></th>
  </tr>
</table>

[2]: https://github.com/nodejs/node/pull/10866

<p align="center"><a href="#table-of-contents"><img src=".documentary/section-breaks/-1.svg?sanitize=true"></a></p>

---
_Source: https://npm.io/package/spawncommand · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._