EXECA Files

Breaking

• Require Node.js 22. (#1243) 04b4454

• The subprocess is now a normal promise, instead of a ChildProcess instance augmented with promise methods. All the methods and properties documented by Execa are unchanged. Node.js-specific ChildProcess APIs (such as .on(), .send(), .ref() and .unref()) must now be accessed through the new subprocess.nodeChildProcess property. (#1255) ade74bf

  :::diff const subprocess = execa('node', ['file.js']);

  • subprocess.on('spawn', onSpawn);
  • subprocess.nodeChildProcess.on('spawn', onSpawn);

• Removed execaCommand() and execaCommandSync(). Use the template string syntax instead, which splits on spaces. If the command is a dynamic string, split it with parseCommandString(). (#1244) 3ced394

  :::diff

  • await execaCommand('npm run build');

  • await execanpm run build;

  • await execaCommand(commandString);

  • await execa${parseCommandString(commandString)};

• Removed the old undocumented stdio: [..., 'ipc'] syntax. Use the ipc: true option instead. (#1245) dcf611c

  :::diff

  • await execa('node', ['file.js'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
  • await execa('node', ['file.js'], {ipc: true});

• When the input or inputFile option is combined with an inherited stdin (for example stdio: 'inherit'), the explicit input is now used, instead of being ignored. To combine multiple inputs, pass an array like stdin: ['inherit', {string: 'input'}]. (#1232) 3ed0544

Improvements

• Terminate the subprocess' descendant processes by using the killDescendants option. This is useful when the subprocess spawns its own processes, such as when using the shell option. (#1256) 84fa0ec

  :::js await execa('npm', ['run', 'build'], {killDescendants: true, timeout: 5000});

• Convert the subprocess to a web stream by using subprocess.readableStream(), subprocess.writableStream() or subprocess.transformStream(). (#1254) 29d9cfc

  :::js await execanpm run build .readableStream() .pipeTo(writableWebStream);

• The value returned by subprocess.pipe() now exposes the destination subprocess' methods, so the piped output can be consumed directly: iterate over its output lines, convert it to a stream, or exchange IPC messages. (#1252) c31c94c

  :::js for await (const line of execanpm run build.pipesort) { console.log(line); }

• Use an additional file descriptor as input by wrapping its stdio value as a {value, input: true} object. Direction-ambiguous values ('pipe', 'inherit', files and transforms) default to output on additional file descriptors. (#1246, [#1249]) 487a3a4 9fbf5ba

  :::js const subprocess = execa({stdio: ['pipe', 'pipe', 'pipe', {value: 'pipe', input: true}]})npm run scaffold;

  const writable = subprocess.writable({to: 'fd3'});

• The transform generator function's chunk argument is now typed based on the transform's mode, instead of always being unknown: string for line transforms, Uint8Array for binary transforms, and unknown in object mode. (#1247) 0a7b4f8

Fixes

• Fixed fd-specific options (verbose, maxBuffer, etc.) when the ipc option is true: fd3 and ipc no longer target the same file descriptor. (#1241) b886883

https://github.com/sindresorhus/execa/compare/v9.6.1...v10.0.0