1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
# execa [](https://travis-ci.org/sindresorhus/execa) [](https://ci.appveyor.com/project/sindresorhus/execa/branch/master) [](https://coveralls.io/github/sindresorhus/execa?branch=master)
> A better [`child_process`](https://nodejs.org/api/child_process.html)
## Why
- Promise interface.
- [Strips EOF](https://github.com/sindresorhus/strip-eof) from the output so you don't have to `stdout.trim()`.
- Supports [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) binaries cross-platform.
- [Improved Windows support.](https://github.com/IndigoUnited/node-cross-spawn#why)
- Higher max buffer. 10 MB instead of 200 KB.
- [Executes locally installed binaries by name.](#preferlocal)
- [Cleans up spawned processes when the parent process dies.](#cleanup)
## Install
```
$ npm install --save execa
```
## Usage
```js
const execa = require('execa');
execa('echo', ['unicorns']).then(result => {
console.log(result.stdout);
//=> 'unicorns'
});
// pipe the child process stdout to the current stdout
execa('echo', ['unicorns']).stdout.pipe(process.stdout);
execa.shell('echo unicorns').then(result => {
console.log(result.stdout);
//=> 'unicorns'
});
// example of catching an error
execa.shell('exit 3').catch(error => {
console.log(error);
/*
{
message: 'Command failed: /bin/sh -c exit 3'
killed: false,
code: 3,
signal: null,
cmd: '/bin/sh -c exit 3',
stdout: '',
stderr: '',
timedOut: false
}
*/
});
```
## API
### execa(file, [arguments], [options])
Execute a file.
Same options as [`child_process.execFile`](https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback).
Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
### execa.stdout(file, [arguments], [options])
Same as `execa()`, but returns only `stdout`.
### execa.stderr(file, [arguments], [options])
Same as `execa()`, but returns only `stderr`.
### execa.shell(command, [options])
Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
Same options as [`child_process.exec`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback).
Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
### execa.sync(file, [arguments], [options])
Execute a file synchronously.
Same options as [`child_process.execFileSync`](https://nodejs.org/api/child_process.html#child_process_child_process_execfilesync_file_args_options), except the default encoding is `utf8` instead of `buffer`.
Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
### execa.shellSync(file, [options])
Execute a command synchronously through the system shell.
Same options as [`child_process.execSync`](https://nodejs.org/api/child_process.html#child_process_child_process_execsync_command_options), except the default encoding is `utf8` instead of `buffer`.
Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
### options
Additional options:
#### stripEof
Type: `boolean`<br>
Default: `true`
[Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output.
#### preferLocal
Type: `boolean`<br>
Default: `true`
Prefer locally installed binaries when looking for a binary to execute.<br>
If you `$ npm install foo`, you can then `execa('foo')`.
#### input
Type: `string` `Buffer` `ReadableStream`
Write some input to the `stdin` of your binary.<br>
Streams are not allowed when using the synchronous methods.
#### reject
Type: `boolean`<br>
Default: `true`
Setting this to `false` resolves the promise with the error instead of rejecting it.
#### cleanup
Type: `boolean`<br>
Default: `true`
Keep track of the spawned process and `kill` it when the parent process exits.
## License
MIT © [Sindre Sorhus](https://sindresorhus.com)
|
