v9.2.0

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)