| /// <reference types="node"/> |
| import {ChildProcess} from 'child_process'; |
| import {Stream, Readable as ReadableStream} from 'stream'; |
| |
| declare namespace execa { |
| type StdioOption = |
| | 'pipe' |
| | 'ipc' |
| | 'ignore' |
| | 'inherit' |
| | Stream |
| | number |
| | undefined; |
| |
| interface CommonOptions<EncodingType> { |
| /** |
| Kill the spawned process when the parent process exits unless either: |
| - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached) |
| - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit |
| |
| @default true |
| */ |
| readonly cleanup?: boolean; |
| |
| /** |
| Prefer locally installed binaries when looking for a binary to execute. |
| |
| If you `$ npm install foo`, you can then `execa('foo')`. |
| |
| @default false |
| */ |
| readonly preferLocal?: boolean; |
| |
| /** |
| Preferred path to find locally installed binaries in (use with `preferLocal`). |
| |
| @default process.cwd() |
| */ |
| readonly localDir?: string; |
| |
| /** |
| Path to the Node.js executable to use in child processes. |
| |
| This can be either an absolute path or a path relative to the `cwd` option. |
| |
| Requires `preferLocal` to be `true`. |
| |
| 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. |
| |
| @default process.execPath |
| */ |
| readonly execPath?: string; |
| |
| /** |
| 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. |
| |
| If the spawned process fails, `error.stdout`, `error.stderr`, and `error.all` will contain the buffered data. |
| |
| @default true |
| */ |
| readonly buffer?: boolean; |
| |
| /** |
| Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). |
| |
| @default 'pipe' |
| */ |
| readonly stdin?: StdioOption; |
| |
| /** |
| Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). |
| |
| @default 'pipe' |
| */ |
| readonly stdout?: StdioOption; |
| |
| /** |
| Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). |
| |
| @default 'pipe' |
| */ |
| readonly stderr?: StdioOption; |
| |
| /** |
| Setting this to `false` resolves the promise with the error instead of rejecting it. |
| |
| @default true |
| */ |
| readonly reject?: boolean; |
| |
| /** |
| Add an `.all` property on the promise and the resolved value. The property contains the output of the process with `stdout` and `stderr` interleaved. |
| |
| @default false |
| */ |
| readonly all?: boolean; |
| |
| /** |
| Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. |
| |
| @default true |
| */ |
| readonly stripFinalNewline?: boolean; |
| |
| /** |
| Set to `false` if you don't want to extend the environment variables when providing the `env` property. |
| |
| @default true |
| */ |
| readonly extendEnv?: boolean; |
| |
| /** |
| Current working directory of the child process. |
| |
| @default process.cwd() |
| */ |
| readonly cwd?: string; |
| |
| /** |
| Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. |
| |
| @default process.env |
| */ |
| readonly env?: NodeJS.ProcessEnv; |
| |
| /** |
| Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified. |
| */ |
| readonly argv0?: string; |
| |
| /** |
| Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration. |
| |
| @default 'pipe' |
| */ |
| readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[]; |
| |
| /** |
| Specify the kind of serialization used for sending messages between processes when using the `stdio: 'ipc'` option or `execa.node()`: |
| - `json`: Uses `JSON.stringify()` and `JSON.parse()`. |
| - `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value) |
| |
| Requires Node.js `13.2.0` or later. |
| |
| [More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization) |
| |
| @default 'json' |
| */ |
| readonly serialization?: 'json' | 'advanced'; |
| |
| /** |
| 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). |
| |
| @default false |
| */ |
| readonly detached?: boolean; |
| |
| /** |
| Sets the user identity of the process. |
| */ |
| readonly uid?: number; |
| |
| /** |
| Sets the group identity of the process. |
| */ |
| readonly gid?: number; |
| |
| /** |
| 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. |
| |
| We recommend against using this option since it is: |
| - not cross-platform, encouraging shell-specific syntax. |
| - slower, because of the additional shell interpretation. |
| - unsafe, potentially allowing command injection. |
| |
| @default false |
| */ |
| readonly shell?: boolean | string; |
| |
| /** |
| 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. |
| |
| @default 'utf8' |
| */ |
| readonly encoding?: EncodingType; |
| |
| /** |
| 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. |
| |
| @default 0 |
| */ |
| readonly timeout?: number; |
| |
| /** |
| Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 100 MB. |
| |
| @default 100_000_000 |
| */ |
| readonly maxBuffer?: number; |
| |
| /** |
| Signal value to be used when the spawned process will be killed. |
| |
| @default 'SIGTERM' |
| */ |
| readonly killSignal?: string | number; |
| |
| /** |
| 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`. |
| |
| @default false |
| */ |
| readonly windowsVerbatimArguments?: boolean; |
| |
| /** |
| 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. |
| |
| @default true |
| */ |
| readonly windowsHide?: boolean; |
| } |
| |
| interface Options<EncodingType = string> extends CommonOptions<EncodingType> { |
| /** |
| Write some input to the `stdin` of your binary. |
| */ |
| readonly input?: string | Buffer | ReadableStream; |
| } |
| |
| interface SyncOptions<EncodingType = string> extends CommonOptions<EncodingType> { |
| /** |
| Write some input to the `stdin` of your binary. |
| */ |
| readonly input?: string | Buffer; |
| } |
| |
| interface NodeOptions<EncodingType = string> extends Options<EncodingType> { |
| /** |
| The Node.js executable to use. |
| |
| @default process.execPath |
| */ |
| readonly nodePath?: string; |
| |
| /** |
| List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable. |
| |
| @default process.execArgv |
| */ |
| readonly nodeOptions?: string[]; |
| } |
| |
| interface ExecaReturnBase<StdoutStderrType> { |
| /** |
| The file and arguments that were run, for logging purposes. |
| |
| This is not escaped and should not be executed directly as a process, including using `execa()` or `execa.command()`. |
| */ |
| command: string; |
| |
| /** |
| Same as `command` but escaped. |
| |
| This is meant to be copy and pasted into a shell, for debugging purposes. |
| Since the escaping is fairly basic, this should not be executed directly as a process, including using `execa()` or `execa.command()`. |
| */ |
| escapedCommand: string; |
| |
| /** |
| The numeric exit code of the process that was run. |
| */ |
| exitCode: number; |
| |
| /** |
| The output of the process on stdout. |
| */ |
| stdout: StdoutStderrType; |
| |
| /** |
| The output of the process on stderr. |
| */ |
| stderr: StdoutStderrType; |
| |
| /** |
| Whether the process failed to run. |
| */ |
| failed: boolean; |
| |
| /** |
| Whether the process timed out. |
| */ |
| timedOut: boolean; |
| |
| /** |
| Whether the process was killed. |
| */ |
| killed: boolean; |
| |
| /** |
| The name of the signal that was used to terminate the process. For example, `SIGFPE`. |
| |
| If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. |
| */ |
| signal?: string; |
| |
| /** |
| A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`. |
| |
| 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. |
| */ |
| signalDescription?: string; |
| } |
| |
| interface ExecaSyncReturnValue<StdoutErrorType = string> |
| extends ExecaReturnBase<StdoutErrorType> { |
| } |
| |
| /** |
| Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance. |
| |
| The child process fails when: |
| - its exit code is not `0` |
| - it was killed with a signal |
| - timing out |
| - being canceled |
| - there's not enough memory or there are already too many child processes |
| */ |
| interface ExecaReturnValue<StdoutErrorType = string> |
| extends ExecaSyncReturnValue<StdoutErrorType> { |
| /** |
| The output of the process with `stdout` and `stderr` interleaved. |
| |
| This is `undefined` if either: |
| - the `all` option is `false` (default value) |
| - `execa.sync()` was used |
| */ |
| all?: StdoutErrorType; |
| |
| /** |
| Whether the process was canceled. |
| */ |
| isCanceled: boolean; |
| } |
| |
| interface ExecaSyncError<StdoutErrorType = string> |
| extends Error, |
| ExecaReturnBase<StdoutErrorType> { |
| /** |
| 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. |
| |
| The child process stderr then stdout are appended to the end, separated with newlines and not interleaved. |
| */ |
| message: string; |
| |
| /** |
| This is the same as the `message` property except it does not include the child process stdout/stderr. |
| */ |
| shortMessage: string; |
| |
| /** |
| 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. |
| |
| This is `undefined` unless the child process exited due to an `error` event or a timeout. |
| */ |
| originalMessage?: string; |
| } |
| |
| interface ExecaError<StdoutErrorType = string> |
| extends ExecaSyncError<StdoutErrorType> { |
| /** |
| The output of the process with `stdout` and `stderr` interleaved. |
| |
| This is `undefined` if either: |
| - the `all` option is `false` (default value) |
| - `execa.sync()` was used |
| */ |
| all?: StdoutErrorType; |
| |
| /** |
| Whether the process was canceled. |
| */ |
| isCanceled: boolean; |
| } |
| |
| interface KillOptions { |
| /** |
| Milliseconds to wait for the child process to terminate before sending `SIGKILL`. |
| |
| Can be disabled with `false`. |
| |
| @default 5000 |
| */ |
| forceKillAfterTimeout?: number | false; |
| } |
| |
| interface ExecaChildPromise<StdoutErrorType> { |
| /** |
| 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). |
| |
| This is `undefined` if either: |
| - the `all` option is `false` (the default value) |
| - 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) |
| */ |
| all?: ReadableStream; |
| |
| catch<ResultType = never>( |
| onRejected?: (reason: ExecaError<StdoutErrorType>) => ResultType | PromiseLike<ResultType> |
| ): Promise<ExecaReturnValue<StdoutErrorType> | ResultType>; |
| |
| /** |
| 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`. |
| */ |
| kill(signal?: string, options?: KillOptions): void; |
| |
| /** |
| 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`. |
| */ |
| cancel(): void; |
| } |
| |
| type ExecaChildProcess<StdoutErrorType = string> = ChildProcess & |
| ExecaChildPromise<StdoutErrorType> & |
| Promise<ExecaReturnValue<StdoutErrorType>>; |
| } |
| |
| declare const execa: { |
| /** |
| Execute a file. |
| |
| Think of this as a mix of `child_process.execFile` and `child_process.spawn`. |
| |
| @param file - The program/script to execute. |
| @param arguments - Arguments to pass to `file` on execution. |
| @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. |
| |
| @example |
| ``` |
| import execa = require('execa'); |
| |
| (async () => { |
| const {stdout} = await execa('echo', ['unicorns']); |
| console.log(stdout); |
| //=> 'unicorns' |
| |
| // Cancelling a spawned process |
| |
| const subprocess = execa('node'); |
| |
| setTimeout(() => { |
| subprocess.cancel() |
| }, 1000); |
| |
| try { |
| await subprocess; |
| } catch (error) { |
| console.log(subprocess.killed); // true |
| console.log(error.isCanceled); // true |
| } |
| })(); |
| |
| // Pipe the child process stdout to the current stdout |
| execa('echo', ['unicorns']).stdout.pipe(process.stdout); |
| ``` |
| */ |
| ( |
| file: string, |
| arguments?: readonly string[], |
| options?: execa.Options |
| ): execa.ExecaChildProcess; |
| ( |
| file: string, |
| arguments?: readonly string[], |
| options?: execa.Options<null> |
| ): execa.ExecaChildProcess<Buffer>; |
| (file: string, options?: execa.Options): execa.ExecaChildProcess; |
| (file: string, options?: execa.Options<null>): execa.ExecaChildProcess< |
| Buffer |
| >; |
| |
| /** |
| Execute a file synchronously. |
| |
| This method throws an `Error` if the command fails. |
| |
| @param file - The program/script to execute. |
| @param arguments - Arguments to pass to `file` on execution. |
| @returns A result `Object` with `stdout` and `stderr` properties. |
| */ |
| sync( |
| file: string, |
| arguments?: readonly string[], |
| options?: execa.SyncOptions |
| ): execa.ExecaSyncReturnValue; |
| sync( |
| file: string, |
| arguments?: readonly string[], |
| options?: execa.SyncOptions<null> |
| ): execa.ExecaSyncReturnValue<Buffer>; |
| sync(file: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue; |
| sync( |
| file: string, |
| options?: execa.SyncOptions<null> |
| ): execa.ExecaSyncReturnValue<Buffer>; |
| |
| /** |
| 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')`. |
| |
| 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. |
| |
| 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`. |
| |
| @param command - The program/script to execute and its arguments. |
| @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. |
| |
| @example |
| ``` |
| import execa = require('execa'); |
| |
| (async () => { |
| const {stdout} = await execa.command('echo unicorns'); |
| console.log(stdout); |
| //=> 'unicorns' |
| })(); |
| ``` |
| */ |
| command(command: string, options?: execa.Options): execa.ExecaChildProcess; |
| command(command: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>; |
| |
| /** |
| Same as `execa.command()` but synchronous. |
| |
| @param command - The program/script to execute and its arguments. |
| @returns A result `Object` with `stdout` and `stderr` properties. |
| */ |
| commandSync(command: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue; |
| commandSync(command: string, options?: execa.SyncOptions<null>): execa.ExecaSyncReturnValue<Buffer>; |
| |
| /** |
| Execute a Node.js script as a child process. |
| |
| 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)): |
| - the current Node version and options are used. This can be overridden using the `nodePath` and `nodeArguments` options. |
| - the `shell` option cannot be used |
| - an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio) |
| |
| @param scriptPath - Node.js script to execute. |
| @param arguments - Arguments to pass to `scriptPath` on execution. |
| @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. |
| */ |
| node( |
| scriptPath: string, |
| arguments?: readonly string[], |
| options?: execa.NodeOptions |
| ): execa.ExecaChildProcess; |
| node( |
| scriptPath: string, |
| arguments?: readonly string[], |
| options?: execa.Options<null> |
| ): execa.ExecaChildProcess<Buffer>; |
| node(scriptPath: string, options?: execa.Options): execa.ExecaChildProcess; |
| node(scriptPath: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>; |
| }; |
| |
| export = execa; |