-
-
Notifications
You must be signed in to change notification settings - Fork 222
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve buffer: false
option with IPC
#1094
Merged
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ehmicky
force-pushed
the
ipc-buffering
branch
2 times, most recently
from
May 24, 2024 19:54
6b3bf45
to
f16f4dd
Compare
renovate bot
added a commit
to andrei-picus-tink/auto-renovate
that referenced
this pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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 pull request
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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR is a continuation of #1092.
It improves the behavior of
buffer: false
with IPC, but in a simpler way than implemented in #1092.It also adds more code comments explaining the logic on how Node.js buffers IPC messages, and how Execa differs from that default behavior.
Finally, this PR adds more tests related to that logic.