sindresorhus/execa (execa)
### [`v9.2.0`](https://togithub.com/sindresorhus/execa/releases/tag/v9.2.0)
[Compare Source](https://togithub.com/sindresorhus/execa/compare/v9.1.0...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://togithub.com/iiroj) for your contribution, [@SimonSiefke](https://togithub.com/SimonSiefke) and [@adymorz](https://togithub.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://togithub.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://togithub.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://togithub.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://togithub.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://togithub.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://togithub.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://togithub.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://togithub.com/sindresorhus/execa/issues/1059), [#1061](https://togithub.com/sindresorhus/execa/issues/1061), [#1076](https://togithub.com/sindresorhus/execa/issues/1076), [#1077](https://togithub.com/sindresorhus/execa/issues/1077), [#1079](https://togithub.com/sindresorhus/execa/issues/1079), [#1082](https://togithub.com/sindresorhus/execa/issues/1082), [#1083](https://togithub.com/sindresorhus/execa/issues/1083), [#1086](https://togithub.com/sindresorhus/execa/issues/1086), [#1087](https://togithub.com/sindresorhus/execa/issues/1087), [#1088](https://togithub.com/sindresorhus/execa/issues/1088), [#1089](https://togithub.com/sindresorhus/execa/issues/1089), [#1090](https://togithub.com/sindresorhus/execa/issues/1090), [#1091](https://togithub.com/sindresorhus/execa/issues/1091), [#1092](https://togithub.com/sindresorhus/execa/issues/1092), [#1094](https://togithub.com/sindresorhus/execa/issues/1094), [#1095](https://togithub.com/sindresorhus/execa/issues/1095), [#1098](https://togithub.com/sindresorhus/execa/issues/1098), [#1104](https://togithub.com/sindresorhus/execa/issues/1104), [#1107](https://togithub.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://togithub.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://togithub.com/sindresorhus/execa/issues/1067), [#1071](https://togithub.com/sindresorhus/execa/issues/1071), [#1075](https://togithub.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://togithub.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://togithub.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://togithub.com/sindresorhus/execa/issues/1066))
- Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://togithub.com/sindresorhus/execa/issues/1059))
- Fix type of `forceKillAfterDelay: true` option. ([#1116](https://togithub.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://togithub.com/sindresorhus/execa/issues/1058))
- Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://togithub.com/sindresorhus/execa/issues/1108))
- Fix accidental publishing of Vim backup files. ([#1074](https://togithub.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://togithub.com/iiroj)) ([#1101](https://togithub.com/sindresorhus/execa/issues/1101))
Configuration
📅 Schedule: Branch creation - "every weekend" (UTC), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about these updates again.
[ ] If you want to rebase/retry this PR, check this box
This PR has been generated by Mend Renovate. View repository job log here.
This PR contains the following updates:
9.1.0->9.2.0Release Notes
sindresorhus/execa (execa)
### [`v9.2.0`](https://togithub.com/sindresorhus/execa/releases/tag/v9.2.0) [Compare Source](https://togithub.com/sindresorhus/execa/compare/v9.1.0...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://togithub.com/iiroj) for your contribution, [@SimonSiefke](https://togithub.com/SimonSiefke) and [@adymorz](https://togithub.com/adymorz) for reporting the bugs fixed in this release, and [@karlhorky](https://togithub.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://togithub.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://togithub.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://togithub.com/sindresorhus/execa/blob/main/docs/api.md#parsecommandstringcommand) can split that string into an array. [More info.](docs/escaping.md) ([#1054](https://togithub.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://togithub.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://togithub.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://togithub.com/sindresorhus/execa/issues/1059), [#1061](https://togithub.com/sindresorhus/execa/issues/1061), [#1076](https://togithub.com/sindresorhus/execa/issues/1076), [#1077](https://togithub.com/sindresorhus/execa/issues/1077), [#1079](https://togithub.com/sindresorhus/execa/issues/1079), [#1082](https://togithub.com/sindresorhus/execa/issues/1082), [#1083](https://togithub.com/sindresorhus/execa/issues/1083), [#1086](https://togithub.com/sindresorhus/execa/issues/1086), [#1087](https://togithub.com/sindresorhus/execa/issues/1087), [#1088](https://togithub.com/sindresorhus/execa/issues/1088), [#1089](https://togithub.com/sindresorhus/execa/issues/1089), [#1090](https://togithub.com/sindresorhus/execa/issues/1090), [#1091](https://togithub.com/sindresorhus/execa/issues/1091), [#1092](https://togithub.com/sindresorhus/execa/issues/1092), [#1094](https://togithub.com/sindresorhus/execa/issues/1094), [#1095](https://togithub.com/sindresorhus/execa/issues/1095), [#1098](https://togithub.com/sindresorhus/execa/issues/1098), [#1104](https://togithub.com/sindresorhus/execa/issues/1104), [#1107](https://togithub.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://togithub.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://togithub.com/sindresorhus/execa/issues/1067), [#1071](https://togithub.com/sindresorhus/execa/issues/1071), [#1075](https://togithub.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://togithub.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://togithub.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://togithub.com/sindresorhus/execa/issues/1066)) - Export the `Message` type, for [IPC](docs/ipc.md). ([#1059](https://togithub.com/sindresorhus/execa/issues/1059)) - Fix type of `forceKillAfterDelay: true` option. ([#1116](https://togithub.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://togithub.com/sindresorhus/execa/issues/1058)) - Fix multiple minor problems with the [`cancelSignal`](docs/termination.md#canceling) option. ([#1108](https://togithub.com/sindresorhus/execa/issues/1108)) - Fix accidental publishing of Vim backup files. ([#1074](https://togithub.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://togithub.com/iiroj)) ([#1101](https://togithub.com/sindresorhus/execa/issues/1101))Configuration
📅 Schedule: Branch creation - "every weekend" (UTC), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about these updates again.
This PR has been generated by Mend Renovate. View repository job log here.