source: trip-planner-front/node_modules/execa/readme.md@ 8d391a1

Last change on this file since 8d391a1 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 8.1 KB
Line 
1# execa [![Build Status: Linux](https://travis-ci.org/sindresorhus/execa.svg?branch=master)](https://travis-ci.org/sindresorhus/execa) [![Build status: Windows](https://ci.appveyor.com/api/projects/status/x5ajamxtjtt93cqv/branch/master?svg=true)](https://ci.appveyor.com/project/sindresorhus/execa/branch/master) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/execa/badge.svg?branch=master)](https://coveralls.io/github/sindresorhus/execa?branch=master)
2
3> A better [`child_process`](https://nodejs.org/api/child_process.html)
4
5
6## Why
7
8- Promise interface.
9- [Strips EOF](https://github.com/sindresorhus/strip-eof) from the output so you don't have to `stdout.trim()`.
10- Supports [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) binaries cross-platform.
11- [Improved Windows support.](https://github.com/IndigoUnited/node-cross-spawn#why)
12- Higher max buffer. 10 MB instead of 200 KB.
13- [Executes locally installed binaries by name.](#preferlocal)
14- [Cleans up spawned processes when the parent process dies.](#cleanup)
15
16
17## Install
18
19```
20$ npm install execa
21```
22
23<a href="https://www.patreon.com/sindresorhus">
24 <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
25</a>
26
27
28## Usage
29
30```js
31const execa = require('execa');
32
33(async () => {
34 const {stdout} = await execa('echo', ['unicorns']);
35 console.log(stdout);
36 //=> 'unicorns'
37})();
38```
39
40Additional examples:
41
42```js
43const execa = require('execa');
44
45(async () => {
46 // Pipe the child process stdout to the current stdout
47 execa('echo', ['unicorns']).stdout.pipe(process.stdout);
48
49
50 // Run a shell command
51 const {stdout} = await execa.shell('echo unicorns');
52 //=> 'unicorns'
53
54
55 // Catching an error
56 try {
57 await execa.shell('exit 3');
58 } catch (error) {
59 console.log(error);
60 /*
61 {
62 message: 'Command failed: /bin/sh -c exit 3'
63 killed: false,
64 code: 3,
65 signal: null,
66 cmd: '/bin/sh -c exit 3',
67 stdout: '',
68 stderr: '',
69 timedOut: false
70 }
71 */
72 }
73})();
74
75// Catching an error with a sync method
76try {
77 execa.shellSync('exit 3');
78} catch (error) {
79 console.log(error);
80 /*
81 {
82 message: 'Command failed: /bin/sh -c exit 3'
83 code: 3,
84 signal: null,
85 cmd: '/bin/sh -c exit 3',
86 stdout: '',
87 stderr: '',
88 timedOut: false
89 }
90 */
91}
92```
93
94
95## API
96
97### execa(file, [arguments], [options])
98
99Execute a file.
100
101Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
102
103Returns 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.
104
105### execa.stdout(file, [arguments], [options])
106
107Same as `execa()`, but returns only `stdout`.
108
109### execa.stderr(file, [arguments], [options])
110
111Same as `execa()`, but returns only `stderr`.
112
113### execa.shell(command, [options])
114
115Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
116
117Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
118
119The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
120
121### execa.sync(file, [arguments], [options])
122
123Execute a file synchronously.
124
125Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
126
127This method throws an `Error` if the command fails.
128
129### execa.shellSync(file, [options])
130
131Execute a command synchronously through the system shell.
132
133Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
134
135### options
136
137Type: `Object`
138
139#### cwd
140
141Type: `string`<br>
142Default: `process.cwd()`
143
144Current working directory of the child process.
145
146#### env
147
148Type: `Object`<br>
149Default: `process.env`
150
151Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
152
153#### extendEnv
154
155Type: `boolean`<br>
156Default: `true`
157
158Set to `false` if you don't want to extend the environment variables when providing the `env` property.
159
160#### argv0
161
162Type: `string`
163
164Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
165
166#### stdio
167
168Type: `string[]` `string`<br>
169Default: `pipe`
170
171Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
172
173#### detached
174
175Type: `boolean`
176
177Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached).
178
179#### uid
180
181Type: `number`
182
183Sets the user identity of the process.
184
185#### gid
186
187Type: `number`
188
189Sets the group identity of the process.
190
191#### shell
192
193Type: `boolean` `string`<br>
194Default: `false`
195
196If `true`, runs `command` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows.
197
198#### stripEof
199
200Type: `boolean`<br>
201Default: `true`
202
203[Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output.
204
205#### preferLocal
206
207Type: `boolean`<br>
208Default: `true`
209
210Prefer locally installed binaries when looking for a binary to execute.<br>
211If you `$ npm install foo`, you can then `execa('foo')`.
212
213#### localDir
214
215Type: `string`<br>
216Default: `process.cwd()`
217
218Preferred path to find locally installed binaries in (use with `preferLocal`).
219
220#### input
221
222Type: `string` `Buffer` `stream.Readable`
223
224Write some input to the `stdin` of your binary.<br>
225Streams are not allowed when using the synchronous methods.
226
227#### reject
228
229Type: `boolean`<br>
230Default: `true`
231
232Setting this to `false` resolves the promise with the error instead of rejecting it.
233
234#### cleanup
235
236Type: `boolean`<br>
237Default: `true`
238
239Keep track of the spawned process and `kill` it when the parent process exits.
240
241#### encoding
242
243Type: `string`<br>
244Default: `utf8`
245
246Specify the character encoding used to decode the `stdout` and `stderr` output.
247
248#### timeout
249
250Type: `number`<br>
251Default: `0`
252
253If timeout is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than timeout milliseconds.
254
255#### buffer
256
257Type: `boolean`<br>
258Default: `true`
259
260Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed.
261
262#### maxBuffer
263
264Type: `number`<br>
265Default: `10000000` (10MB)
266
267Largest amount of data in bytes allowed on `stdout` or `stderr`.
268
269#### killSignal
270
271Type: `string` `number`<br>
272Default: `SIGTERM`
273
274Signal value to be used when the spawned process will be killed.
275
276#### stdin
277
278Type: `string` `number` `Stream` `undefined` `null`<br>
279Default: `pipe`
280
281Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
282
283#### stdout
284
285Type: `string` `number` `Stream` `undefined` `null`<br>
286Default: `pipe`
287
288Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
289
290#### stderr
291
292Type: `string` `number` `Stream` `undefined` `null`<br>
293Default: `pipe`
294
295Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
296
297#### windowsVerbatimArguments
298
299Type: `boolean`<br>
300Default: `false`
301
302If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`.
303
304
305## Tips
306
307### Save and pipe output from a child process
308
309Let's say you want to show the output of a child process in real-time while also saving it to a variable.
310
311```js
312const execa = require('execa');
313const getStream = require('get-stream');
314
315const stream = execa('echo', ['foo']).stdout;
316
317stream.pipe(process.stdout);
318
319getStream(stream).then(value => {
320 console.log('child output:', value);
321});
322```
323
324
325## License
326
327MIT © [Sindre Sorhus](https://sindresorhus.com)
Note: See TracBrowser for help on using the repository browser.