Deprecating old ipc option
#1056
Comments
|
I would do |
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 18, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 19, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 21, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 21, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 21, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 21, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 21, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Aug 22, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 23, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 24, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 25, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 27, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 27, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 28, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 29, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Aug 30, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 1, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 2, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 3, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 4, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 5, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 6, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 7, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 8, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this issue
Sep 9, 2024
| datasource | package | from | to |
| ---------- | ------- | ----- | ----- |
| npm | execa | 5.1.1 | 9.3.1 |
## [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
## [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
## [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
## [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
## [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
## [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
## [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
## [v8.0.1](https://github.com/sindresorhus/execa/releases/tag/v8.0.1)
##### Fixes
- Fix and document support for the [`{encoding: 'buffer'}` option](https://github.com/sindresorhus/execa#encoding). It is the same as `{encoding: null}`, but preferred over it. ([#572](https://github.com/sindresorhus/execa/issues/572))
## [v8.0.0](https://github.com/sindresorhus/execa/releases/tag/v8.0.0)
##### Breaking
- Require Node.js 16.17.0 and later ([#569](https://github.com/sindresorhus/execa/issues/569))
## [v7.2.0](https://github.com/sindresorhus/execa/releases/tag/v7.2.0)
- Add `cwd` error property ([#565](https://github.com/sindresorhus/execa/issues/565)) [`f57fdec`](https://github.com/sindresorhus/execa/commit/f57fdec)
## [v7.1.1](https://github.com/sindresorhus/execa/releases/tag/v7.1.1)
#### Features
- Improve error message when `` $.sync(options)`command` `` is used instead of [`` $(options).sync`command` ``](https://github.com/sindresorhus/execa#synccommand) ([#551](https://github.com/sindresorhus/execa/issues/551))
#### Bug fixes
- Fix argument concatenation when using [`` $`command argument${value}` ``](https://github.com/sindresorhus/execa#command) ([#553](https://github.com/sindresorhus/execa/issues/553))
- Fix default value of the [`stdin` option](https://github.com/sindresorhus/execa#stdin) when using [`` $`command` ``](https://github.com/sindresorhus/execa#command): it should be `inherit` ([#550](https://github.com/sindresorhus/execa/issues/550))
## [v7.1.0](https://github.com/sindresorhus/execa/releases/tag/v7.1.0)
#### Features
- Add [`$` method](https://github.com/sindresorhus/execa#command) to write Node.js scripts like zx. For more information, please see [this blog post](https://medium.com/@ehmicky/shell-free-scripts-with-execa-7-885fb3b42f83), [this section](https://github.com/sindresorhus/execa#scripts-interface) and [this page](https://github.com/sindresorhus/execa/blob/main/docs/scripts.md). Thanks [@aaronccasanova](https://github.com/aaronccasanova) for this great feature!
```js
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
```
- Add [`.pipeStdout()`](https://github.com/sindresorhus/execa#pipestdouttarget), [`.pipeStderr()`](https://github.com/sindresorhus/execa#pipestderrtarget) and [`.pipeAll()`](https://github.com/sindresorhus/execa#pipealltarget) methods to redirect `stdout`/`stderr` to a file, a stream or another process.
```js
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');
```
- Add [`inputFile` option](https://github.com/sindresorhus/execa#inputfile) to use a file as `stdin`.
```js
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
```
- Add [`verbose` option](https://github.com/sindresorhus/execa#verbose) to print each command on `stderr` before executing it. This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
<!---->
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows
## [v7.0.0](https://github.com/sindresorhus/execa/releases/tag/v7.0.0)
##### Breaking
- Require Node.js 14 and later ([#497](https://github.com/sindresorhus/execa/issues/497)) [`a09cbc0`](https://github.com/sindresorhus/execa/commit/a09cbc0)
##### Fixes
- Emit `end` event on streams when process fails ([#518](https://github.com/sindresorhus/execa/issues/518)) [`30c7a7a`](https://github.com/sindresorhus/execa/commit/30c7a7a)
- Fix incorrect `execaNode` signature in `index.d.ts` ([#506](https://github.com/sindresorhus/execa/issues/506)) [`1f7677c`](https://github.com/sindresorhus/execa/commit/1f7677c)
## [v6.1.0](https://github.com/sindresorhus/execa/releases/tag/v6.1.0)
- Support [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) ([#490](https://github.com/sindresorhus/execa/issues/490)) [`c6e791a`](https://github.com/sindresorhus/execa/commit/c6e791a)
- Allow `cwd` and `localDir` options to be URLs ([#492](https://github.com/sindresorhus/execa/issues/492)) [`93ab929`](https://github.com/sindresorhus/execa/commit/93ab929)
## [v6.0.0](https://github.com/sindresorhus/execa/releases/tag/v6.0.0)
##### Breaking
- Require Node.js 12.20 ([#478](https://github.com/sindresorhus/execa/issues/478)) [`7707880`](https://github.com/sindresorhus/execa/commit/7707880)
- This package is now pure ESM. **Please [read this](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
- Moved from a default export to named exports.
- `require('execa')` → `import {execa} from 'execa'`
- `require('execa').sync` → `import {execaSync} from 'execa'`
- `require('execa').command` → `import {execaCommand} from 'execa'`
- `require('execa').commandSync` → `import {execaCommandSync} from 'execa'`
- `require('execa').node` → `import {execaNode} from 'execa'`
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Sep 16, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Sep 16, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Sep 16, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Sep 16, 2024
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
renovate bot
added a commit
to mmkal/eslint-plugin-mmkal
that referenced
this issue
Sep 17, 2024
##### [v9.4.0](https://github.com/sindresorhus/execa/compare/v9.3.1...1b9b9bbf17705c28019f770cecd9920db206f824)
##### [v9.3.1](https://github.com/sindresorhus/execa/compare/v9.3.0...0a51f7cbef53e7290a3604e585e1b2e61da37367)
##### [v9.3.0](https://github.com/sindresorhus/execa/releases/tag/v9.3.0)
#### Features
- The [`verbose`](docs/api.md#optionsverbose) option can now be [a function](docs/api.md#verbose-function) to [customize logging](docs/debugging.md#custom-logging). ([#1130](https://github.com/sindresorhus/execa/issues/1130))
##### [v9.2.0](https://github.com/sindresorhus/execa/releases/tag/v9.2.0)
This release includes a [new set of methods](docs/ipc.md) to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows [passing](docs/input.md#any-input-type) and [returning](docs/output.md#any-output-type) almost any message type to/from a Node.js subprocess. Also, [debugging](docs/ipc.md#debugging) IPC is now much easier.
Moreover, a new [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option has also been added to [terminate a subprocess gracefully](docs/termination.md#graceful-termination).
For a deeper dive-in, please check and share the [release post](https://medium.com/@ehmicky/ipc-made-easy-with-execa-9-2-939c6a358731)!
Thanks [@iiroj](https://github.com/iiroj) for your contribution, [@SimonSiefke](https://github.com/SimonSiefke) and [@adymorz](https://github.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://github.com/karlhorky) for improving the documentation!
#### Deprecations
- Passing `'ipc'` to the [`stdio`](docs/api.md#optionsstdio) option has been deprecated. It will be removed in the next major release. Instead, the [`ipc: true`](docs/api.md#optionsipc) option should be used. ([#1056](https://github.com/sindresorhus/execa/issues/1056))
```diff
- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});
```
- The [`execaCommand()`](https://github.com/sindresorhus/execa/blob/v9.1.0/docs/api.md#execacommandcommand-options) method has been deprecated. It will be removed in the next major release. If most cases, the [template string syntax](docs/execution.md#template-string-syntax) should be used instead.
```diff
- import {execaCommand} from 'execa';
+ import {execa} from 'execa';
- await execaCommand('npm run build');
+ await execa`npm run build`;
const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;
const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;
```
If the file and/or multiple arguments are supplied as a single string, [parseCommandString(command)](https://github.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://github.com/sindresorhus/execa/issues/1054))
```diff
- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';
const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;
// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);
```
#### Features
- Add [`gracefulCancel`](docs/api.md#optionsgracefulcancel) option and [`getCancelSignal()`](docs/api.md#getcancelsignal) method to [terminate a subprocess gracefully](docs/termination.md#graceful-termination). [`error.isGracefullyCanceled`](docs/api.md#errorisgracefullycanceled) was also added. ([#1109](https://github.com/sindresorhus/execa/issues/1109))
- Add [`error.isForcefullyTerminated`](docs/api.md#errorisforcefullyterminated). It is `true` when the subprocess was terminated by the [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) option. ([#1111](https://github.com/sindresorhus/execa/issues/1111))
- New methods to simplify exchanging messages between the current process and the subprocess. [More info.](docs/ipc.md) ([#1059](https://github.com/sindresorhus/execa/issues/1059), [#1061](https://github.com/sindresorhus/execa/issues/1061), [#1076](https://github.com/sindresorhus/execa/issues/1076), [#1077](https://github.com/sindresorhus/execa/issues/1077), [#1079](https://github.com/sindresorhus/execa/issues/1079), [#1082](https://github.com/sindresorhus/execa/issues/1082), [#1083](https://github.com/sindresorhus/execa/issues/1083), [#1086](https://github.com/sindresorhus/execa/issues/1086), [#1087](https://github.com/sindresorhus/execa/issues/1087), [#1088](https://github.com/sindresorhus/execa/issues/1088), [#1089](https://github.com/sindresorhus/execa/issues/1089), [#1090](https://github.com/sindresorhus/execa/issues/1090), [#1091](https://github.com/sindresorhus/execa/issues/1091), [#1092](https://github.com/sindresorhus/execa/issues/1092), [#1094](https://github.com/sindresorhus/execa/issues/1094), [#1095](https://github.com/sindresorhus/execa/issues/1095), [#1098](https://github.com/sindresorhus/execa/issues/1098), [#1104](https://github.com/sindresorhus/execa/issues/1104), [#1107](https://github.com/sindresorhus/execa/issues/1107))
- The current process sends messages with [`subprocess.sendMessage(message)`](docs/api.md#subprocesssendmessagemessage-sendmessageoptions) and receives them with [`subprocess.getOneMessage()`](docs/api.md#subprocessgetonemessagegetonemessageoptions). [`subprocess.getEachMessage()`](docs/api.md#subprocessgeteachmessagegeteachmessageoptions) listens to multiple messages.
- The subprocess uses [`sendMessage(message)`](docs/api.md#sendmessagemessage-sendmessageoptions), [`getOneMessage()`](docs/api.md#getonemessagegetonemessageoptions) and [`getEachMessage()`](docs/api.md#geteachmessagegeteachmessageoptions) instead. Those are the same methods, but imported directly from the `'execa'` module.
- The [`ipcInput`](docs/ipc.md#send-an-initial-message) option sends an IPC message from the current process to the subprocess as it starts. This enables [passing almost any input type](docs/input.md#any-input-type) to a Node.js subprocess. ([#1068](https://github.com/sindresorhus/execa/issues/1068))
- The [`result.ipcOutput`](docs/ipc.md#retrieve-all-messages) array contains all the IPC messages sent by the subprocess to the current process. This enables [returning almost any output type](docs/output.md#any-output-type) from a Node.js subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067), [#1071](https://github.com/sindresorhus/execa/issues/1071), [#1075](https://github.com/sindresorhus/execa/issues/1075))
- The [error message](docs/errors.md#error-message) now [contains every IPC message](docs/ipc.md#debugging) sent by the subprocess. ([#1067](https://github.com/sindresorhus/execa/issues/1067))
- The [`verbose: 'full'`](docs/api.md#optionsverbose) option now logs every IPC message sent by the subprocess, for debugging. More info [here](docs/ipc.md#debugging) and [there](docs/output.md#stdoutstderr-specific-options). ([#1063](https://github.com/sindresorhus/execa/issues/1063))
#### Types
- Add [`ExecaMethod`](docs/typescript.md#available-types), [`ExecaNodeMethod`](docs/typescript.md#available-types) and [`ExecaScriptMethod`](docs/typescript.md#available-types), [`ExecaSyncMethod`](docs/typescript.md#synchronous-execution) and [`ExecaScriptSyncMethod`](docs/typescript.md#synchronous-execution) types. ([#1066](https://github.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://github.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://github.com/sindresorhus/execa/issues/1116))
#### Bug fixes
- Fix passing a [`{file}`](docs/output.md#file-output) to both the [`stdin`](docs/api.md#optionsstdin) and the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) options. ([#1058](https://github.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://github.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://github.com/sindresorhus/execa/issues/1074))
- Fix `engines.node` field in [`package.json`](package.json). Supported Node.js version is `^18.19.0` or `>=20.5.0`. (by [@iiroj](https://github.com/iiroj)) ([#1101](https://github.com/sindresorhus/execa/issues/1101))
##### [v9.1.0](https://github.com/sindresorhus/execa/releases/tag/v9.1.0)
#### Features (types)
- Export [`TemplateExpression`](docs/typescript.md#available-types) type. ([#1049](https://github.com/sindresorhus/execa/issues/1049))
##### [v9.0.2](https://github.com/sindresorhus/execa/releases/tag/v9.0.2)
#### Bug fixes (types)
- Do not require using `--lib dom` for TypeScript users ([#1043](https://github.com/sindresorhus/execa/issues/1043), [#1044](https://github.com/sindresorhus/execa/issues/1044))
- Fix type of the `reject` option ([#1046](https://github.com/sindresorhus/execa/issues/1046))
##### [v9.0.1](https://github.com/sindresorhus/execa/releases/tag/v9.0.1)
#### Bug fixes (types)
- Fix types not being importable ([#1033](https://github.com/sindresorhus/execa/issues/1033)) [`3bdab60`](https://github.com/sindresorhus/execa/commit/3bdab60)
- Fix complexity bug with types ([#1037](https://github.com/sindresorhus/execa/issues/1037)) [`6cc519b`](https://github.com/sindresorhus/execa/commit/6cc519b)
- Fix complexity bug with types ([#1035](https://github.com/sindresorhus/execa/issues/1035)) [`fee011d`](https://github.com/sindresorhus/execa/commit/fee011d)
##### [v9.0.0](https://github.com/sindresorhus/execa/releases/tag/v9.0.0)
This major release brings many important features including:
- [Split the output](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) into lines, or [progressively iterate](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#3a26) over them.
- [Transform or filter](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#cbd6) the input/output using [simple functions](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#399a).
- Print the output [to the terminal](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f) while still retrieving it programmatically.
- Redirect the input/output [from/to a file](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#693f).
- [Advanced piping](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#ec17) between multiple subprocesses.
- Improved [verbose mode](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#2913), for debugging.
- More [detailed errors](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#40d7), including when [terminating subprocesses](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#668c).
- Enhanced [template string syntax](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#725b).
- [Global/shared options](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#bcbf).
- [Web streams](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#5731) and Transform streams support.
- [Convert the subprocess](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f#47b9) to a stream.
- [New documentation](https://github.com/sindresorhus/execa#documentation) with many examples.
Please check the [release post](https://medium.com/@ehmicky/execa-9-release-d0d5daaa097f) for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.
Thanks [@younggglcy](https://github.com/younggglcy), [@koshic](https://github.com/koshic), [@am0o0](https://github.com/am0o0) and [@codesmith-emmy](https://github.com/codesmith-emmy) for your help!
***
One of the maintainers [@ehmicky](https://github.com/ehmicky) is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify [Build](https://www.netlify.com/platform/core/build/), [Plugins](https://www.netlify.com/integrations/) and Configuration for 2.5 years. Feel free to contact him on [his website](https://www.mickael-hebert.com) or on [LinkedIn](https://www.linkedin.com/in/mickaelhebert/)!
***
#### Breaking changes
- Minimal supported Node.js version is now `18.19.0`. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726))
- When the [`encoding` option](docs/api.md#optionsencoding) is `'buffer'`, the output ([`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall)) is now an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer). For more information, see [this blog post](https://sindresorhus.com/blog/goodbye-nodejs-buffer). (by [@younggglcy](https://github.com/younggglcy)) ([#586](https://github.com/sindresorhus/execa/issues/586))
```js
const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array
```
- Renamed some of the allowed values for the [`encoding`](docs/api.md#optionsencoding) option. ([#586](https://github.com/sindresorhus/execa/issues/586), [#928](https://github.com/sindresorhus/execa/issues/928))
```diff
- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});
- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});
- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});
- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});
```
- Passing a file path to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, a [`{file: './path'}` object](docs/output.md#file-output) should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});
- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+ stdout: {file: 'output.txt'},
+ stderr: {file: 'output.txt'},
+});
```
- Passing a [writable stream](https://nodejs.org/api/stream.html#class-streamwritable) to `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` has been removed. Instead, the stream should be passed to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. If the stream [does not have a file descriptor](docs/streams.md#file-descriptors), [`['pipe', stream]`](docs/output.md#multiple-targets) should be passed instead. ([#752](https://github.com/sindresorhus/execa/issues/752))
```diff
- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});
- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});
- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+ stdout: ['pipe', stream],
+ stderr: ['pipe', stream],
+});
```
- The `subprocess.pipeStdout()`, `subprocess.pipeStderr()` and `subprocess.pipeAll()` methods have been renamed to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options). The command and its arguments can be passed to `subprocess.pipe()` directly, without calling `execa()` a second time. The [`from`](docs/api.md#pipeoptionsfrom) piping option can specify `'stdout'` (the default value), `'stderr'` or `'all'`. ([#757](https://github.com/sindresorhus/execa/issues/757))
```diff
- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);
- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});
- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});
```
- Renamed the `signal` option to [`cancelSignal`](docs/api.md#optionscancelsignal). ([#880](https://github.com/sindresorhus/execa/issues/880))
```diff
- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});
```
- Renamed `error.killed` to [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625))
```diff
try {
await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
// ...
}
}
```
- `subprocess.cancel()` has been removed. Please use either [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) or the [`cancelSignal`](docs/api.md#optionscancelsignal) option instead. ([#711](https://github.com/sindresorhus/execa/issues/711))
```diff
- subprocess.cancel();
+ subprocess.kill();
```
- Renamed the `forceKillAfterTimeout` option to [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay). Also, it is now passed to [`execa()`](docs/api.md#execafile-arguments-options) instead of [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error). ([#714](https://github.com/sindresorhus/execa/issues/714), [#723](https://github.com/sindresorhus/execa/issues/723))
```diff
- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');
```
- The [`verbose`](docs/api.md#optionsverbose) option is now a string enum instead of a boolean. `false` has been renamed to `'none'` and `true` has been renamed to [`'short'`](docs/debugging.md#short-mode). ([#884](https://github.com/sindresorhus/execa/issues/884))
```diff
- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});
- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});
```
- The `execPath` option has been renamed to [`nodePath`](docs/api.md#optionsnodepath). It is now a noop unless the [`node`](docs/api.md#optionsnode) option is `true`. Also, it now works even if the [`preferLocal`](docs/api.md#optionspreferlocal) option is `false`. ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
```diff
- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});
```
- The [default value](docs/ipc.md#message-type) for the [`serialization`](docs/api.md#optionsserialization) option is now [`'advanced'`](https://nodejs.org/api/child_process.html#advanced-serialization) instead of `'json'`. In particular, when calling [`subprocess.send(object)`](docs/api.md#subprocesssendmessage) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. ([#905](https://github.com/sindresorhus/execa/issues/905))
```diff
- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});
```
- If [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) or [`subprocess.all`](docs/api.md#subprocessall) is manually piped, the [`.pipe()`](https://nodejs.org/api/stream.html#readablepipedestination-options) call must now happen as soon as `subprocess` is created. Otherwise, the output at the beginning of the subprocess might be missing. ([#658](https://github.com/sindresorhus/execa/issues/658), [#747](https://github.com/sindresorhus/execa/issues/747))
```diff
const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
subprocess.stdout.pipe(process.stdout);
- }, 0);
```
- Signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option cannot be lowercase anymore. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
```diff
- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});
- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');
```
#### Features
##### Execution
- Use the [template string syntax](docs/execution.md#template-string-syntax) with any method (including [`execa()`](docs/api.md#execacommand)), as opposed to only [`$`](docs/api.md#file-arguments-options). Conversely, `$` can now use the [regular array syntax](docs/scripts.md#template-string-syntax). ([#933](https://github.com/sindresorhus/execa/issues/933))
- A command's template string can span [multiple lines](docs/execution.md#multiple-lines). ([#843](https://github.com/sindresorhus/execa/issues/843))
- [Share options](docs/execution.md#globalshared-options) between multiple calls, or set global options, by using [`execa(options)`](docs/api#execaoptions). ([#933](https://github.com/sindresorhus/execa/issues/933), [#965](https://github.com/sindresorhus/execa/issues/965))
- Pass a file URL (as opposed to a file path string) to [`execa()`](docs/api.md#execafile-arguments-options), [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), the [`inputFile`](docs/api.md#optionsinputfile) option, the [`nodePath`](docs/api.md#optionsnodepath) option or the [`shell`](docs/api.md#optionsshell) option. ([#630](https://github.com/sindresorhus/execa/issues/630), [#631](https://github.com/sindresorhus/execa/issues/631), [#632](https://github.com/sindresorhus/execa/issues/632), [#635](https://github.com/sindresorhus/execa/issues/635))
##### Text lines
- [Split the output](docs/lines.md#simple-splitting) into text lines by using the [`lines`](docs/api.md#optionslines) option. ([#741](https://github.com/sindresorhus/execa/issues/741), [#929](https://github.com/sindresorhus/execa/issues/929), [#931](https://github.com/sindresorhus/execa/issues/931), [#948](https://github.com/sindresorhus/execa/issues/948), [#951](https://github.com/sindresorhus/execa/issues/951), [#957](https://github.com/sindresorhus/execa/issues/957))
- Subprocess is now an [async iterable](docs/api.md#subprocesssymbolasynciterator), [iterating over the output](docs/lines.md#progressive-splitting) lines while the subprocess is running. ([#923](https://github.com/sindresorhus/execa/issues/923))
##### Piping multiple subprocesses
- Simpler syntax: pass the [command directly](docs/pipe.md#array-syntax) to [`subprocess.pipe()`](docs/api.md#subprocesspipefile-arguments-options) without calling [`execa()`](docs/api.md#execafile-arguments-options). A [template string](docs/pipe.md#template-string-syntax) can also be used. ([#840](https://github.com/sindresorhus/execa/issues/840), [#859](https://github.com/sindresorhus/execa/issues/859), [#864](https://github.com/sindresorhus/execa/issues/864))
- [Wait for both subprocesses](docs/pipe.md#result) to complete. [Error handling](docs/pipe.md#errors) has been improved too. ([#757](https://github.com/sindresorhus/execa/issues/757), [#778](https://github.com/sindresorhus/execa/issues/778), [#834](https://github.com/sindresorhus/execa/issues/834), [#854](https://github.com/sindresorhus/execa/issues/854))
- Retrieve the [result](docs/pipe.md#result) of each subprocess (not only the last one) by using [`result.pipedFrom`](docs/api.md#resultpipedfrom) and [`error.pipedFrom`](docs/api.md#resultpipedfrom). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe 1 or [many subprocesses](docs/pipe.md#multiple-sources-1-destination) to 1 or [many subprocesses](docs/pipe.md#1-source-multiple-destinations). ([#834](https://github.com/sindresorhus/execa/issues/834))
- Pipe subprocesses using [other file descriptors](docs/pipe.md#source-file-descriptor) than `stdin`/`stdout`/`stderr` by using the [`from`](docs/api.md#pipeoptionsfrom) and [`to`](docs/api.md#pipeoptionsto) piping options. ([#757](https://github.com/sindresorhus/execa/issues/757), [#834](https://github.com/sindresorhus/execa/issues/834), [#903](https://github.com/sindresorhus/execa/issues/903), [#920](https://github.com/sindresorhus/execa/issues/920))
- [Cancel piping](docs/pipe.md#unpipe) subprocesses by using the [`unpipeSignal`](docs/api.md#pipeoptionsunpipesignal) piping option. ([#834](https://github.com/sindresorhus/execa/issues/834), [#852](https://github.com/sindresorhus/execa/issues/852))
##### Input/output
- Pass an array with [multiple values](docs/output.md#multiple-targets) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options. For example, [`stdout: ['inherit', 'pipe']`](docs/output.md#multiple-targets) prints the output [to the terminal](docs/output.md#terminal-output) while still [returning it](docs/output.md#stdout-and-stderr) as [`result.stdout`](docs/api.md#resultstdout). ([#643](https://github.com/sindresorhus/execa/issues/643), [#765](https://github.com/sindresorhus/execa/issues/765), [#941](https://github.com/sindresorhus/execa/issues/941), [#954](https://github.com/sindresorhus/execa/issues/954))
- Redirect the [input](docs/input.md#file-input)/[output](docs/output.md#file-output) from/to a file by passing a `{file: './path'}` object or a file URL to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#610](https://github.com/sindresorhus/execa/issues/610), [#614](https://github.com/sindresorhus/execa/issues/614), [#621](https://github.com/sindresorhus/execa/issues/621), [#671](https://github.com/sindresorhus/execa/issues/671), [#1004](https://github.com/sindresorhus/execa/issues/1004))
- [Transform](docs/transform.md) or [filter](docs/transform.md#filtering) the input/output by passing a generator function to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#693](https://github.com/sindresorhus/execa/issues/693), [#697](https://github.com/sindresorhus/execa/issues/697), [#698](https://github.com/sindresorhus/execa/issues/698), [#699](https://github.com/sindresorhus/execa/issues/699), [#709](https://github.com/sindresorhus/execa/issues/709), [#736](https://github.com/sindresorhus/execa/issues/736), [#737](https://github.com/sindresorhus/execa/issues/737), [#739](https://github.com/sindresorhus/execa/issues/739), [#740](https://github.com/sindresorhus/execa/issues/740), [#746](https://github.com/sindresorhus/execa/issues/746), [#748](https://github.com/sindresorhus/execa/issues/748), [#755](https://github.com/sindresorhus/execa/issues/755), [#756](https://github.com/sindresorhus/execa/issues/756), [#780](https://github.com/sindresorhus/execa/issues/780), [#783](https://github.com/sindresorhus/execa/issues/783), [#867](https://github.com/sindresorhus/execa/issues/867), [#915](https://github.com/sindresorhus/execa/issues/915), [#916](https://github.com/sindresorhus/execa/issues/916), [#917](https://github.com/sindresorhus/execa/issues/917), [#919](https://github.com/sindresorhus/execa/issues/919), [#924](https://github.com/sindresorhus/execa/issues/924), [#926](https://github.com/sindresorhus/execa/issues/926), [#945](https://github.com/sindresorhus/execa/issues/945), [#969](https://github.com/sindresorhus/execa/issues/969))
- Provide some [binary input](docs/binary.md#binary-input) by passing an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) to the [`input`](docs/api.md#optionsinput) or [`stdin`](docs/api.md#optionsstdin) option. ([`834e372`](https://github.com/sindresorhus/execa/commit/834e3726), [#670](https://github.com/sindresorhus/execa/issues/670), [#1029](https://github.com/sindresorhus/execa/issues/1029))
- Provide some [progressive input](docs/streams.md#iterables-as-input) by passing a sync/async [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) to the [`stdin`](docs/api.md#optionsstdin) option. ([#604](https://github.com/sindresorhus/execa/issues/604), [#944](https://github.com/sindresorhus/execa/issues/944))
- Provide [multiple inputs](docs/output.md#multiple-targets) by combining the [`stdin`](docs/api.md#optionsstdin), [`input`](docs/api.md#optionsinput) and [`inputFile`](docs/api.md#optionsinputfile) options. ([#666](https://github.com/sindresorhus/execa/issues/666))
- Return [other file descriptors](docs/output.md#additional-file-descriptors) than [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) by using [`result.stdio`](docs/api.md#resultstdio). ([#676](https://github.com/sindresorhus/execa/issues/676))
- [Specify different values](docs/output.md#stdoutstderr-specific-options) for [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) with the following options: [`verbose`](docs/api.md#optionsverbose), [`lines`](docs/api.md#optionslines), [`stripFinalNewline`](docs/api.md#optionsstripfinalnewline), [`maxBuffer`](docs/api.md#optionsmaxbuffer), [`buffer`](docs/api.md#optionsbuffer). ([#966](https://github.com/sindresorhus/execa/issues/966), [#970](https://github.com/sindresorhus/execa/issues/970), [#971](https://github.com/sindresorhus/execa/issues/971), [#972](https://github.com/sindresorhus/execa/issues/972), [#973](https://github.com/sindresorhus/execa/issues/973), [#974](https://github.com/sindresorhus/execa/issues/974))
##### Streams
- Redirect the input/output from/to a [web stream](docs/streams.md#web-streams) by passing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#615](https://github.com/sindresorhus/execa/issues/615), [#619](https://github.com/sindresorhus/execa/issues/619), [#645](https://github.com/sindresorhus/execa/issues/645))
- [Transform or filter](docs/transform.md#duplextransform-streams) the input/output by passing a [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex), Node.js [`Transform`](https://nodejs.org/api/stream.html#class-streamtransform) or web [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) to the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option. ([#937](https://github.com/sindresorhus/execa/issues/937), [#938](https://github.com/sindresorhus/execa/issues/938))
- [Convert the subprocess](docs/streams.md#converting-a-subprocess-to-a-stream) to a stream by using [`subprocess.readable()`](docs/api.md#subprocessreadablereadableoptions), [`subprocess.writable()`](docs/api.md#subprocesswritablewritableoptions) or [`subprocess.duplex()`](docs/api.md#subprocessduplexduplexoptions). ([#912](https://github.com/sindresorhus/execa/issues/912), [#922](https://github.com/sindresorhus/execa/issues/922), [#958](https://github.com/sindresorhus/execa/issues/958))
##### Verbose mode
- Print the subprocess' [completion, duration and errors](docs/debugging.md#short-mode) with the [`verbose: 'short'`](docs/api.md#optionsverbose) or `verbose: 'full'` option. ([#887](https://github.com/sindresorhus/execa/issues/887), [#890](https://github.com/sindresorhus/execa/issues/890))
- Print the subprocess' [output](docs/debugging.md#full-mode) with the [`verbose: 'full'`](docs/api.md#optionsverbose) option. ([#884](https://github.com/sindresorhus/execa/issues/884), [#950](https://github.com/sindresorhus/execa/issues/950), [#962](https://github.com/sindresorhus/execa/issues/962), [#990](https://github.com/sindresorhus/execa/issues/990))
- Prettier formatting and [colors](docs/debugging.md#colors) with the [`verbose`](docs/api.md#optionsverbose) option. ([#883](https://github.com/sindresorhus/execa/issues/883), [#893](https://github.com/sindresorhus/execa/issues/893), [#894](https://github.com/sindresorhus/execa/issues/894))
##### Debugging
- Retrieve the subprocess' [duration](docs/debugging.md#duration) by using [`result.durationMs`](docs/api.md#resultdurationms) and [`error.durationMs`](docs/api.md#resultdurationms). ([#896](https://github.com/sindresorhus/execa/issues/896))
- Retrieve the subprocess' [current directory](docs/environment.md#current-directory) by using [`result.cwd`](docs/api.md#resultcwd). Previously only [`error.cwd`](docs/api.md#execaerror) was available. Also, `result.cwd` and `error.cwd` are now normalized to absolute file paths. ([#803](https://github.com/sindresorhus/execa/issues/803))
- Printing [`result.escapedCommand`](docs/api.md#resultescapedcommand) in a terminal [is now safe](docs/debugging.md#command). ([#875](https://github.com/sindresorhus/execa/issues/875))
##### Errors
- The [`ExecaError`](docs/api.md#execaerror) and [`ExecaSyncError`](docs/api.md#execasyncerror) classes [are now exported](docs/errors.md#subprocess-failure). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Find the subprocess failure's [root cause](docs/termination.md#error-message-and-stack-trace) by using [`error.cause`](docs/api.md#errorcause). ([#911](https://github.com/sindresorhus/execa/issues/911))
- Know whether [the subprocess failed](docs/errors.md#failure-reason) due to the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option by using [`error.isMaxBuffer`](docs/api.md#errorismaxbuffer). ([#963](https://github.com/sindresorhus/execa/issues/963))
- Improved [`error.message`](docs/api.md#errormessage): [`error.stdout`](docs/api.md#resultstdout) and [`error.stderr`](docs/api.md#resultstderr) are now [interleaved](docs/output.md#interleaved-output) if the [`all`](docs/api.md#optionsall) option is `true`. [Additional file descriptors](docs/output.md#additional-file-descriptors) are now printed too. Also, the [formatting](docs/errors.md#error-message) has been improved. ([#676](https://github.com/sindresorhus/execa/issues/676), [#705](https://github.com/sindresorhus/execa/issues/705), [#991](https://github.com/sindresorhus/execa/issues/991), [#992](https://github.com/sindresorhus/execa/issues/992))
- [Control characters](https://en.wikipedia.org/wiki/Control_character) in [`error.message`](docs/api.md#errormessage) are now escaped, so they don't result in visual bugs when printed in a terminal. ([#879](https://github.com/sindresorhus/execa/issues/879))
- Improved stack trace when an [`error`](https://nodejs.org/api/stream.html#event-error\_1) event is emitted on [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#814](https://github.com/sindresorhus/execa/issues/814))
##### Termination
- Specify an [error message or stack trace](docs/termination.md#error-message-and-stack-trace) when terminating a subprocess by passing an error instance to [`subprocess.kill()`](docs/api.md#subprocesskillerror). ([#811](https://github.com/sindresorhus/execa/issues/811), [#836](https://github.com/sindresorhus/execa/issues/836), [#1023](https://github.com/sindresorhus/execa/issues/1023))
- The [`forceKillAfterDelay`](docs/api.md#optionsforcekillafterdelay) and [`killSignal`](docs/api.md#optionskillsignal) options [now apply to terminations](docs/termination.md#default-signal) due not only to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) but [also to](docs/termination.md#forceful-termination) the [`cancelSignal`](docs/api.md#optionscancelsignal), [`timeout`](docs/api.md#optionstimeout), [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`cleanup`](docs/api.md#optionscleanup) options. ([#714](https://github.com/sindresorhus/execa/issues/714), [#728](https://github.com/sindresorhus/execa/issues/728))
##### Node.js files
- Use the [`nodePath`](docs/api.md#optionsnodepath) and [`nodeOptions`](docs/api.md#optionsnodeoptions) options with [any method](docs/api.md#methods), as opposed to only [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options), by passing the [`node: true`](docs/api.md#optionsnode) option. ([#804](https://github.com/sindresorhus/execa/issues/804), [#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815))
- When using [`execaNode()`](docs/api.md#execanodescriptpath-arguments-options) or the [`node: true`](docs/api.md#optionsnode) option, the [current Node.js version](docs/node.md#nodejs-version) is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the [same Node.js version](docs/api.md#optionsnodepath). ([#812](https://github.com/sindresorhus/execa/issues/812), [#815](https://github.com/sindresorhus/execa/issues/815), [#1011](https://github.com/sindresorhus/execa/issues/1011))
##### Synchronous execution
- Use the [`all`](docs/api.md#optionsall) and [`buffer: false`](docs/api.md#optionsbuffer) options with [`execaSync()`](docs/api.md#execasyncfile-arguments-options), as opposed to only [`execa()`](docs/api.md#execafile-arguments-options). ([#953](https://github.com/sindresorhus/execa/issues/953), [#956](https://github.com/sindresorhus/execa/issues/956))
- Added the [`$.s`](docs/api.md#file-arguments-options) alias for [`$.sync`](docs/api.md#file-arguments-options). ([#594](https://github.com/sindresorhus/execa/issues/594))
##### Inter-process communication
- Use the [`ipc: true`](docs/api.md#optionsipc) option, as [opposed to the more verbose](docs/ipc.md#exchanging-messages) [`stdio: ['pipe', 'pipe', 'pipe', 'ipc']`](docs/api.md#optionsstdio) option. ([#794](https://github.com/sindresorhus/execa/issues/794))
##### Input validation
- Improved the validation of the [`input`](docs/api.md#optionsinput), [`timeout`](docs/api.md#optionstimeout), [`cwd`](docs/api.md#optionscwd), [`detached`](docs/api.md#optionsdetached), [`cancelSignal`](docs/api.md#optionscancelsignal) and [`encoding`](docs/api.md#optionsencoding) options. ([#668](https://github.com/sindresorhus/execa/issues/668), [#715](https://github.com/sindresorhus/execa/issues/715), [#803](https://github.com/sindresorhus/execa/issues/803), [#928](https://github.com/sindresorhus/execa/issues/928), [#940](https://github.com/sindresorhus/execa/issues/940))
- Improved the validation of the arguments passed to [`execa()`](docs/api.md#execafile-arguments-options) and the [other exported methods](docs/api.md#methods). ([#838](https://github.com/sindresorhus/execa/issues/838), [#873](https://github.com/sindresorhus/execa/issues/873), [#899](https://github.com/sindresorhus/execa/issues/899))
- Improved the validation of signals passed to [`subprocess.kill()`](docs/api.md#subprocesskillsignal-error) and to the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
#### Bug fixes
- Fixed passing `undefined` values as [options](docs/api.md#options). This now uses the option's default value. ([#712](https://github.com/sindresorhus/execa/issues/712))
- Fixed the process crashing when the [`inputFile`](docs/api.md#optionsinputfile) option points to a missing file. ([#609](https://github.com/sindresorhus/execa/issues/609))
- Fixed the process crashing when the [`buffer`](docs/api.md#optionsbuffer) option is `false` and [`subprocess.stdout`](docs/api.md#subprocessstdout) [errors](https://nodejs.org/api/stream.html#event-error\_1). ([#729](https://github.com/sindresorhus/execa/issues/729))
- Fixed the process crashing when passing [`'overlapped'`](docs/windows.md#asynchronous-io) to the [`stdout`](docs/api.md#optionsstdout) or [`stderr`](docs/api.md#optionsstderr) option with [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#949](https://github.com/sindresorhus/execa/issues/949))
- Fixed the process crashing when multiple [`'error'`](https://nodejs.org/api/child_process.html#event-error) events are emitted on the subprocess. ([#790](https://github.com/sindresorhus/execa/issues/790))
- Fixed the [`reject: false`](docs/api.md#optionsreject) option not being used when the subprocess [fails to spawn](docs/errors.md#failure-reason). ([#734](https://github.com/sindresorhus/execa/issues/734))
- Fixed [some inaccuracies](docs/errors.md#failure-reason) with [`error.isTerminated`](docs/api.md#erroristerminated). ([#625](https://github.com/sindresorhus/execa/issues/625), [#719](https://github.com/sindresorhus/execa/issues/719))
- It is now `true` when the subprocess fails due to the [`timeout`](docs/api.md#optionstimeout) option.
- It is now `true` when calling [`process.kill(subprocess.pid)`](https://nodejs.org/api/process.html#processkillpid-signal), except on Windows.
- It is now `false` when using [non-terminating signals](https://nodejs.org/api/child_process.html#subprocesskillsignal) such as `subprocess.kill(0)`.
- Fixed missing [`error.signal`](docs/api.md#errorsignal) and [`error.signalDescription`](docs/api.md#errorsignaldescription) when the subprocess [is terminated](docs/termination.md#canceling) by the [`cancelSignal`](docs/api.md#optionscancelsignal) option. ([#724](https://github.com/sindresorhus/execa/issues/724))
- Fixed a situation where the [error](docs/api.md#execaerror) returned by an [`execa()`](docs/api.md#execafile-arguments-options) call might be modified by another `execa()` call. ([#796](https://github.com/sindresorhus/execa/issues/796), [#806](https://github.com/sindresorhus/execa/issues/806), [#911](https://github.com/sindresorhus/execa/issues/911))
- Fixed the [`verbose`](docs/api.md#optionsverbose) option [printing the command](docs/debugging.md#short-mode) in the wrong order. ([#600](https://github.com/sindresorhus/execa/issues/600))
- Fixed using both the [`maxBuffer`](docs/api.md#optionsmaxbuffer) and [`encoding`](docs/api.md#optionsencoding) options. For example, when using [`encoding: 'hex'`](docs/binary.md#encoding), `maxBuffer` will now be measured in hexadecimal characters. Also, [`error.stdout`](docs/api.md#resultstdout), [`error.stderr`](docs/api.md#resultstderr) and [`error.all`](docs/api.md#resultall) were previously not applying the `maxBuffer` option. ([#652](https://github.com/sindresorhus/execa/issues/652), [#696](https://github.com/sindresorhus/execa/issues/696))
- Fixed the [`maxBuffer`](docs/api.md#optionsmaxbuffer) option [not truncating](docs/output.md#big-output) [`result.stdout`](docs/api.md#resultstdout) and [`result.stderr`](docs/api.md#resultstderr) when using [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#960](https://github.com/sindresorhus/execa/issues/960))
- Fixed empty output when using the [`buffer: true`](docs/api.md#optionsbuffer) option (its default value) and [iterating](https://nodejs.org/api/stream.html#readablesymbolasynciterator) over [`subprocess.stdout`](docs/api.md#subprocessstdout) or [`subprocess.stderr`](docs/api.md#subprocessstderr). ([#908](https://github.com/sindresorhus/execa/issues/908))
- Fixed [`subprocess.all`](docs/api.md#subprocessall) stream incorrectly being in [object mode](https://nodejs.org/api/stream.html#object-mode). ([#717](https://github.com/sindresorhus/execa/issues/717))
- Ensured [`subprocess.stdout`](docs/api.md#subprocessstdout) and [`subprocess.stderr`](docs/api.md#subprocessstderr) are properly [flushed](https://nodejs.org/api/stream.html#buffering) when the subprocess fails. ([#647](https://github.com/sindresorhus/execa/issues/647))
- Fixed a race condition leading to random behavior with the [`timeout`](docs/api.md#optionstimeout) option. ([#727](https://github.com/sindresorhus/execa/issues/727))
#### Types (breaking changes)
- Renamed `CommonOptions` type to [`Options`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#678](https://github.com/sindresorhus/execa/issues/678), [#682](https://github.com/sindresorhus/execa/issues/682))
```diff
import type {Options} from 'execa';
- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};
```
- Renamed `NodeOptions` type to [`Options`](types/arguments/options.d.ts). ([#804](https://github.com/sindresorhus/execa/issues/804))
```diff
import type {Options} from 'execa';
- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};
```
- Renamed `KillOptions` type to [`Options`](types/arguments/options.d.ts). ([#714](https://github.com/sindresorhus/execa/issues/714))
```diff
import type {Options} from 'execa';
- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};
```
- Removed generic parameters from the [`Options`](types/arguments/options.d.ts) and [`SyncOptions`](types/arguments/options.d.ts) types. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Options} from 'execa';
- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};
```
- Renamed `ExecaChildProcess` type to [`ResultPromise`](types/subprocess/subprocess.d.ts). This is the type of [`execa()`](docs/api.md#execafile-arguments-options)'s [return value](docs/api.md#return-value), which is both a [`Promise<Result>`](docs/api.md#result) and a [`Subprocess`](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {ResultPromise, Result} from 'execa';
- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();
```
- Renamed `ExecaChildPromise` type to [`Subprocess`](types/subprocess/subprocess.d.ts). This is the type of the [subprocess instance](docs/api.md#subprocess). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1007](https://github.com/sindresorhus/execa/issues/1007), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Subprocess} from 'execa';
- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();
```
- Renamed `ExecaReturnBase`, `ExecaReturnValue` and `ExecaSyncReturnValue` type to [`Result`](types/return/result.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncResult`](types/return/result.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#897](https://github.com/sindresorhus/execa/issues/897), [#1009](https://github.com/sindresorhus/execa/issues/1009))
```diff
import type {Result, SyncResult} from 'execa';
- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);
- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);
```
- Renamed the type of the [`stdin`](docs/api.md#optionsstdin) option from `StdioOption` to [`StdinOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdinSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdinOption} from 'execa';
- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});
```
- Renamed the type of the [`stdout`](docs/api.md#optionsstdout) and [`stderr`](docs/api.md#optionsstderr) options from `StdioOption` to [`StdoutStderrOption`](types/stdio/type.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`StdoutStderrSyncOption`](types/stdio/type.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008), [#1012](https://github.com/sindresorhus/execa/issues/1012))
```diff
import {execa, type StdoutStderrOption} from 'execa';
- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});
```
- Renamed the type of the [`stdio`](docs/api.md#optionsstdio) option from `StdioOption[]` to [`Options['stdio']`](types/arguments/options.d.ts) (for [`execa()`](docs/api.md#execafile-arguments-options)) and [`SyncOptions['stdio']`](types/arguments/options.d.ts) (for [`execaSync()`](docs/api.md#execasyncfile-arguments-options)). ([#942](https://github.com/sindresorhus/execa/issues/942), [#1008](https://github.com/sindresorhus/execa/issues/1008))
```diff
import {execa, type Options} from 'execa';
- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});
```
- The optional generic parameter passed to the [`Result`](types/return/result.d.ts), [`SyncResult`](types/return/result.d.ts), [`ExecaError`](types/return/final-error.d.ts), [`ExecaSyncError`](types/return/final-error.d.ts), [`ResultPromise`](types/subprocess/subprocess.d.ts) and [`Subprocess`](types/subprocess/subprocess.d.ts) types is now an [`Options`](types/arguments/options.d.ts) type. ([#681](https://github.com/sindresorhus/execa/issues/681))
```diff
import type {Result} from 'execa';
- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});
```
#### Types (improvements)
- Stricter types for the [`stdin`](docs/api.md#optionsstdin), [`stdout`](docs/api.md#optionsstdout), [`stderr`](docs/api.md#optionsstderr) and [`stdio`](docs/api.md#optionsstdio) options. ([#634](https://github.com/sindresorhus/execa/issues/634), [#943](https://github.com/sindresorhus/execa/issues/943), [#952](https://github.com/sindresorhus/execa/issues/952))
- Stricter types for [`result.stdout`](docs/api.md#resultstdout), [`result.stderr`](docs/api.md#resultstderr), [`result.all`](docs/api.md#resultall), [`subprocess.stdout`](docs/api.md#subprocessstdout), [`subprocess.stderr`](docs/api.md#subprocessstderr) and [`subprocess.all`](docs/api.md#subprocessall). ([#681](https://github.com/sindresorhus/execa/issues/681), [#684](https://github.com/sindresorhus/execa/issues/684), [#687](https://github.com/sindresorhus/execa/issues/687), [#689](https://github.com/sindresorhus/execa/issues/689), [#833](https://github.com/sindresorhus/execa/issues/833))
- Stricter types for the [synchronous methods](docs/execution.md#synchronous-execution) like [`execaSync()`](docs/api.md#execasyncfile-arguments-options). ([#678](https://github.com/sindresorhus/execa/issues/678), [#939](https://github.com/sindresorhus/execa/issues/939))
- Stricter types for the [`reject`](docs/api.md#optionsreject) option. ([#688](https://github.com/sindresorhus/execa/issues/688))
- Stricter types for [`error.signal`](docs/api.md#errorsignal) and the [`killSignal`](docs/api.md#optionskillsignal) option. ([#1025](https://github.com/sindresorhus/execa/issues/1025))
- Fixed the type of [`error.exitCode`](docs/api.md#errorexitcode), since that field is sometimes `undefined`. ([#680](https://github.com/sindresorhus/execa/issues/680))
- Refactored and improved the types. (by [@koshic](https://github.com/koshic)) ([#583](https://github.com/sindresorhus/execa/issues/583))
#### Documentation
- Added [user guides](readme.md#documentation) to let you explore each feature with many examples. ([#989](https://github.com/sindresorhus/execa/issues/989), [#996](https://github.com/sindresorhus/execa/issues/996), [#1015](https://github.com/sindresorhus/execa/issues/1015), [#1022](https://github.com/sindresorhus/execa/issues/1022), [#1026](https://github.com/sindresorhus/execa/issues/1026))
- Improved the [documentation](readme.md#documentation) and fixed inaccuracies. ([#626](https://github.com/sindresorhus/execa/issues/626), [#637](https://github.com/sindresorhus/execa/issues/637), [#640](https://github.com/sindresorhus/execa/issues/640), [#641](https://github.com/sindresorhus/execa/issues/641), [#644](https://github.com/sindresorhus/execa/issues/644), [#669](https://github.com/sindresorhus/execa/issues/669), [#680](https://github.com/sindresorhus/execa/issues/680), [#710](https://github.com/sindresorhus/execa/issues/710), [#759](https://github.com/sindresorhus/execa/issues/759), [#800](https://github.com/sindresorhus/execa/issues/800), [#801](https://github.com/sindresorhus/execa/issues/801), [#802](https://github.com/sindresorhus/execa/issues/802), [#860](https://github.com/sindresorhus/execa/issues/860), [#870](https://github.com/sindresorhus/execa/issues/870), [#876](https://github.com/sindresorhus/execa/issues/876), [#888](https://github.com/sindresorhus/execa/issues/888), [#907](https://github.com/sindresorhus/execa/issues/907), [#921](https://github.com/sindresorhus/execa/issues/921), [#935](https://github.com/sindresorhus/execa/issues/935), [#967](https://github.com/sindresorhus/execa/issues/967), [#968](https://github.com/sindresorhus/execa/issues/968), [#994](https://github.com/sindresorhus/execa/issues/994), [#998](https://github.com/sindresorhus/execa/issues/998), [#999](https://github.com/sindresorhus/execa/issues/999), [#1000](https://github.com/sindresorhus/execa/issues/1000), [#1003](https://github.com/sindresorhus/execa/issues/1003), [#1005](https://github.com/sindresorhus/execa/issues/1005), [#1006](https://github.com/sindresorhus/execa/issues/1006), [#1010](https://github.com/sindresorhus/execa/issues/1010))
- Fixed the examples for the [Script interface](docs/bash.md). (by [@am0o0](https://github.com/am0o0)) ([#575](https://github.com/sindresorhus/execa/issues/575))
- Corrected some English grammar mistakes. (by [@codesmith-emmy](https://github.com/codesmith-emmy)) ([#731](https://github.com/sindresorhus/execa/issues/731))
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We've replaced the
{stdio: [..., 'ipc']}option with the simpler{ipc: true}. The old syntax has been undocumented. However, it's still currently supported, for backward compatibility.In the next major release, should we remove support the old syntax? Possible options:
Which one do you prefer @sindresorhus?
Note: we probably should wait for many months before doing any new major release. We just did a big major release with many breaking changes. So this issue is for future planning, not immediate action.
The text was updated successfully, but these errors were encountered: