v9.2.0

Compare Source

This release includes a new set of methods to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows passing and returning almost any message type to/from a Node.js subprocess. Also, debugging IPC is now much easier.

Moreover, a new gracefulCancel option has also been added to terminate a subprocess gracefully.

For a deeper dive-in, please check and share the release post!

Thanks @​iiroj for your contribution, @​SimonSiefke and @​adymorz for reporting the bugs fixed in this release, and @​karlhorky for improving the documentation!

Deprecations

• Passing 'ipc' to the stdio option has been deprecated. It will be removed in the next major release. Instead, the ipc: true option should be used. (#​1056)

- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});

• The execaCommand() method has been deprecated. It will be removed in the next major release. If most cases, the template string syntax should be used instead.

- 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) can split that string into an array. More info. (#​1054)

- 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 option and getCancelSignal() method to terminate a subprocess gracefully. error.isGracefullyCanceled was also added. (#​1109)
• Add error.isForcefullyTerminated. It is true when the subprocess was terminated by the forceKillAfterDelay option. (#​1111)
• New methods to simplify exchanging messages between the current process and the subprocess. More info. (#​1059, #​1061, #​1076, #​1077, #​1079, #​1082, #​1083, #​1086, #​1087, #​1088, #​1089, #​1090, #​1091, #​1092, #​1094, #​1095, #​1098, #​1104, #​1107)
  • The current process sends messages with subprocess.sendMessage(message) and receives them with subprocess.getOneMessage(). subprocess.getEachMessage() listens to multiple messages.
  • The subprocess uses sendMessage(message), getOneMessage() and getEachMessage() instead. Those are the same methods, but imported directly from the 'execa' module.
• The ipcInput option sends an IPC message from the current process to the subprocess as it starts. This enables passing almost any input type to a Node.js subprocess. (#​1068)
• The result.ipcOutput array contains all the IPC messages sent by the subprocess to the current process. This enables returning almost any output type from a Node.js subprocess. (#​1067, #​1071, #​1075)
• The error message now contains every IPC message sent by the subprocess. (#​1067)
• The verbose: 'full' option now logs every IPC message sent by the subprocess, for debugging. More info here and there. (#​1063)

Types

• Add ExecaMethod, ExecaNodeMethod and ExecaScriptMethod, ExecaSyncMethod and ExecaScriptSyncMethod types. (#​1066)
• Export the Message type, for IPC. (#​1059)
• Fix type of forceKillAfterDelay: true option. (#​1116)

Bug fixes

• Fix passing a {file} to both the stdin and the stdout or stderr options. (#​1058)
• Fix multiple minor problems with the cancelSignal option. (#​1108)
• Fix accidental publishing of Vim backup files. (#​1074)
• Fix engines.node field in package.json. Supported Node.js version is ^18.19.0 or >=20.5.0. (by @​iiroj) (#​1101)