source: frontend/node_modules/execa/index.d.ts

Last change on this file was 9af201e, checked in by MBK <marija.karapandzova@…>, 11 days ago

Fix frontend appearance
  • Property mode set to 100644
File size: 17.3 KB
RevLine 
[9af201e]1/// <reference types="node"/>
2import {ChildProcess} from 'child_process';
3import {Stream, Readable as ReadableStream} from 'stream';
4
5declare namespace execa {
6 type StdioOption =
7 | 'pipe'
8 | 'ipc'
9 | 'ignore'
10 | 'inherit'
11 | Stream
12 | number
13 | undefined;
14
15 interface CommonOptions<EncodingType> {
16 /**
17 Kill the spawned process when the parent process exits unless either:
18 - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached)
19 - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit
20
21 @default true
22 */
23 readonly cleanup?: boolean;
24
25 /**
26 Prefer locally installed binaries when looking for a binary to execute.
27
28 If you `$ npm install foo`, you can then `execa('foo')`.
29
30 @default false
31 */
32 readonly preferLocal?: boolean;
33
34 /**
35 Preferred path to find locally installed binaries in (use with `preferLocal`).
36
37 @default process.cwd()
38 */
39 readonly localDir?: string;
40
41 /**
42 Path to the Node.js executable to use in child processes.
43
44 This can be either an absolute path or a path relative to the `cwd` option.
45
46 Requires `preferLocal` to be `true`.
47
48 For example, this can be used together with [`get-node`](https://github.com/ehmicky/get-node) to run a specific Node.js version in a child process.
49
50 @default process.execPath
51 */
52 readonly execPath?: string;
53
54 /**
55 Buffer the output from the spawned process. When set to `false`, you must read the output of `stdout` and `stderr` (or `all` if the `all` option is `true`). Otherwise the returned promise will not be resolved/rejected.
56
57 If the spawned process fails, `error.stdout`, `error.stderr`, and `error.all` will contain the buffered data.
58
59 @default true
60 */
61 readonly buffer?: boolean;
62
63 /**
64 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
65
66 @default 'pipe'
67 */
68 readonly stdin?: StdioOption;
69
70 /**
71 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
72
73 @default 'pipe'
74 */
75 readonly stdout?: StdioOption;
76
77 /**
78 Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
79
80 @default 'pipe'
81 */
82 readonly stderr?: StdioOption;
83
84 /**
85 Setting this to `false` resolves the promise with the error instead of rejecting it.
86
87 @default true
88 */
89 readonly reject?: boolean;
90
91 /**
92 Add an `.all` property on the promise and the resolved value. The property contains the output of the process with `stdout` and `stderr` interleaved.
93
94 @default false
95 */
96 readonly all?: boolean;
97
98 /**
99 Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
100
101 @default true
102 */
103 readonly stripFinalNewline?: boolean;
104
105 /**
106 Set to `false` if you don't want to extend the environment variables when providing the `env` property.
107
108 @default true
109 */
110 readonly extendEnv?: boolean;
111
112 /**
113 Current working directory of the child process.
114
115 @default process.cwd()
116 */
117 readonly cwd?: string;
118
119 /**
120 Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
121
122 @default process.env
123 */
124 readonly env?: NodeJS.ProcessEnv;
125
126 /**
127 Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
128 */
129 readonly argv0?: string;
130
131 /**
132 Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
133
134 @default 'pipe'
135 */
136 readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[];
137
138 /**
139 Specify the kind of serialization used for sending messages between processes when using the `stdio: 'ipc'` option or `execa.node()`:
140 - `json`: Uses `JSON.stringify()` and `JSON.parse()`.
141 - `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)
142
143 Requires Node.js `13.2.0` or later.
144
145 [More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)
146
147 @default 'json'
148 */
149 readonly serialization?: 'json' | 'advanced';
150
151 /**
152 Prepare 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).
153
154 @default false
155 */
156 readonly detached?: boolean;
157
158 /**
159 Sets the user identity of the process.
160 */
161 readonly uid?: number;
162
163 /**
164 Sets the group identity of the process.
165 */
166 readonly gid?: number;
167
168 /**
169 If `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.
170
171 We recommend against using this option since it is:
172 - not cross-platform, encouraging shell-specific syntax.
173 - slower, because of the additional shell interpretation.
174 - unsafe, potentially allowing command injection.
175
176 @default false
177 */
178 readonly shell?: boolean | string;
179
180 /**
181 Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string.
182
183 @default 'utf8'
184 */
185 readonly encoding?: EncodingType;
186
187 /**
188 If `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.
189
190 @default 0
191 */
192 readonly timeout?: number;
193
194 /**
195 Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 100 MB.
196
197 @default 100_000_000
198 */
199 readonly maxBuffer?: number;
200
201 /**
202 Signal value to be used when the spawned process will be killed.
203
204 @default 'SIGTERM'
205 */
206 readonly killSignal?: string | number;
207
208 /**
209 If `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`.
210
211 @default false
212 */
213 readonly windowsVerbatimArguments?: boolean;
214
215 /**
216 On Windows, do not create a new console window. Please note this also prevents `CTRL-C` [from working](https://github.com/nodejs/node/issues/29837) on Windows.
217
218 @default true
219 */
220 readonly windowsHide?: boolean;
221 }
222
223 interface Options<EncodingType = string> extends CommonOptions<EncodingType> {
224 /**
225 Write some input to the `stdin` of your binary.
226 */
227 readonly input?: string | Buffer | ReadableStream;
228 }
229
230 interface SyncOptions<EncodingType = string> extends CommonOptions<EncodingType> {
231 /**
232 Write some input to the `stdin` of your binary.
233 */
234 readonly input?: string | Buffer;
235 }
236
237 interface NodeOptions<EncodingType = string> extends Options<EncodingType> {
238 /**
239 The Node.js executable to use.
240
241 @default process.execPath
242 */
243 readonly nodePath?: string;
244
245 /**
246 List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
247
248 @default process.execArgv
249 */
250 readonly nodeOptions?: string[];
251 }
252
253 interface ExecaReturnBase<StdoutStderrType> {
254 /**
255 The file and arguments that were run, for logging purposes.
256
257 This is not escaped and should not be executed directly as a process, including using `execa()` or `execa.command()`.
258 */
259 command: string;
260
261 /**
262 Same as `command` but escaped.
263
264 This is meant to be copy and pasted into a shell, for debugging purposes.
265 Since the escaping is fairly basic, this should not be executed directly as a process, including using `execa()` or `execa.command()`.
266 */
267 escapedCommand: string;
268
269 /**
270 The numeric exit code of the process that was run.
271 */
272 exitCode: number;
273
274 /**
275 The output of the process on stdout.
276 */
277 stdout: StdoutStderrType;
278
279 /**
280 The output of the process on stderr.
281 */
282 stderr: StdoutStderrType;
283
284 /**
285 Whether the process failed to run.
286 */
287 failed: boolean;
288
289 /**
290 Whether the process timed out.
291 */
292 timedOut: boolean;
293
294 /**
295 Whether the process was killed.
296 */
297 killed: boolean;
298
299 /**
300 The name of the signal that was used to terminate the process. For example, `SIGFPE`.
301
302 If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.
303 */
304 signal?: string;
305
306 /**
307 A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.
308
309 If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.
310 */
311 signalDescription?: string;
312 }
313
314 interface ExecaSyncReturnValue<StdoutErrorType = string>
315 extends ExecaReturnBase<StdoutErrorType> {
316 }
317
318 /**
319 Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
320
321 The child process fails when:
322 - its exit code is not `0`
323 - it was killed with a signal
324 - timing out
325 - being canceled
326 - there's not enough memory or there are already too many child processes
327 */
328 interface ExecaReturnValue<StdoutErrorType = string>
329 extends ExecaSyncReturnValue<StdoutErrorType> {
330 /**
331 The output of the process with `stdout` and `stderr` interleaved.
332
333 This is `undefined` if either:
334 - the `all` option is `false` (default value)
335 - `execa.sync()` was used
336 */
337 all?: StdoutErrorType;
338
339 /**
340 Whether the process was canceled.
341 */
342 isCanceled: boolean;
343 }
344
345 interface ExecaSyncError<StdoutErrorType = string>
346 extends Error,
347 ExecaReturnBase<StdoutErrorType> {
348 /**
349 Error message when the child process failed to run. In addition to the underlying error message, it also contains some information related to why the child process errored.
350
351 The child process stderr then stdout are appended to the end, separated with newlines and not interleaved.
352 */
353 message: string;
354
355 /**
356 This is the same as the `message` property except it does not include the child process stdout/stderr.
357 */
358 shortMessage: string;
359
360 /**
361 Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa.
362
363 This is `undefined` unless the child process exited due to an `error` event or a timeout.
364 */
365 originalMessage?: string;
366 }
367
368 interface ExecaError<StdoutErrorType = string>
369 extends ExecaSyncError<StdoutErrorType> {
370 /**
371 The output of the process with `stdout` and `stderr` interleaved.
372
373 This is `undefined` if either:
374 - the `all` option is `false` (default value)
375 - `execa.sync()` was used
376 */
377 all?: StdoutErrorType;
378
379 /**
380 Whether the process was canceled.
381 */
382 isCanceled: boolean;
383 }
384
385 interface KillOptions {
386 /**
387 Milliseconds to wait for the child process to terminate before sending `SIGKILL`.
388
389 Can be disabled with `false`.
390
391 @default 5000
392 */
393 forceKillAfterTimeout?: number | false;
394 }
395
396 interface ExecaChildPromise<StdoutErrorType> {
397 /**
398 Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr).
399
400 This is `undefined` if either:
401 - the `all` option is `false` (the default value)
402 - both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio)
403 */
404 all?: ReadableStream;
405
406 catch<ResultType = never>(
407 onRejected?: (reason: ExecaError<StdoutErrorType>) => ResultType | PromiseLike<ResultType>
408 ): Promise<ExecaReturnValue<StdoutErrorType> | ResultType>;
409
410 /**
411 Same as the original [`child_process#kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal), except if `signal` is `SIGTERM` (the default value) and the child process is not terminated after 5 seconds, force it by sending `SIGKILL`.
412 */
413 kill(signal?: string, options?: KillOptions): void;
414
415 /**
416 Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`.
417 */
418 cancel(): void;
419 }
420
421 type ExecaChildProcess<StdoutErrorType = string> = ChildProcess &
422 ExecaChildPromise<StdoutErrorType> &
423 Promise<ExecaReturnValue<StdoutErrorType>>;
424}
425
426declare const execa: {
427 /**
428 Execute a file.
429
430 Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
431
432 @param file - The program/script to execute.
433 @param arguments - Arguments to pass to `file` on execution.
434 @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.
435
436 @example
437 ```
438 import execa = require('execa');
439
440 (async () => {
441 const {stdout} = await execa('echo', ['unicorns']);
442 console.log(stdout);
443 //=> 'unicorns'
444
445 // Cancelling a spawned process
446
447 const subprocess = execa('node');
448
449 setTimeout(() => {
450 subprocess.cancel()
451 }, 1000);
452
453 try {
454 await subprocess;
455 } catch (error) {
456 console.log(subprocess.killed); // true
457 console.log(error.isCanceled); // true
458 }
459 })();
460
461 // Pipe the child process stdout to the current stdout
462 execa('echo', ['unicorns']).stdout.pipe(process.stdout);
463 ```
464 */
465 (
466 file: string,
467 arguments?: readonly string[],
468 options?: execa.Options
469 ): execa.ExecaChildProcess;
470 (
471 file: string,
472 arguments?: readonly string[],
473 options?: execa.Options<null>
474 ): execa.ExecaChildProcess<Buffer>;
475 (file: string, options?: execa.Options): execa.ExecaChildProcess;
476 (file: string, options?: execa.Options<null>): execa.ExecaChildProcess<
477 Buffer
478 >;
479
480 /**
481 Execute a file synchronously.
482
483 This method throws an `Error` if the command fails.
484
485 @param file - The program/script to execute.
486 @param arguments - Arguments to pass to `file` on execution.
487 @returns A result `Object` with `stdout` and `stderr` properties.
488 */
489 sync(
490 file: string,
491 arguments?: readonly string[],
492 options?: execa.SyncOptions
493 ): execa.ExecaSyncReturnValue;
494 sync(
495 file: string,
496 arguments?: readonly string[],
497 options?: execa.SyncOptions<null>
498 ): execa.ExecaSyncReturnValue<Buffer>;
499 sync(file: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
500 sync(
501 file: string,
502 options?: execa.SyncOptions<null>
503 ): execa.ExecaSyncReturnValue<Buffer>;
504
505 /**
506 Same as `execa()` except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execa.command('echo unicorns')`.
507
508 If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.
509
510 The `shell` option must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.
511
512 @param command - The program/script to execute and its arguments.
513 @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.
514
515 @example
516 ```
517 import execa = require('execa');
518
519 (async () => {
520 const {stdout} = await execa.command('echo unicorns');
521 console.log(stdout);
522 //=> 'unicorns'
523 })();
524 ```
525 */
526 command(command: string, options?: execa.Options): execa.ExecaChildProcess;
527 command(command: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
528
529 /**
530 Same as `execa.command()` but synchronous.
531
532 @param command - The program/script to execute and its arguments.
533 @returns A result `Object` with `stdout` and `stderr` properties.
534 */
535 commandSync(command: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
536 commandSync(command: string, options?: execa.SyncOptions<null>): execa.ExecaSyncReturnValue<Buffer>;
537
538 /**
539 Execute a Node.js script as a child process.
540
541 Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
542 - the current Node version and options are used. This can be overridden using the `nodePath` and `nodeArguments` options.
543 - the `shell` option cannot be used
544 - an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
545
546 @param scriptPath - Node.js script to execute.
547 @param arguments - Arguments to pass to `scriptPath` on execution.
548 @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.
549 */
550 node(
551 scriptPath: string,
552 arguments?: readonly string[],
553 options?: execa.NodeOptions
554 ): execa.ExecaChildProcess;
555 node(
556 scriptPath: string,
557 arguments?: readonly string[],
558 options?: execa.Options<null>
559 ): execa.ExecaChildProcess<Buffer>;
560 node(scriptPath: string, options?: execa.Options): execa.ExecaChildProcess;
561 node(scriptPath: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
562};
563
564export = execa;
Note: See TracBrowser for help on using the repository browser.