@npmcli/promise-spawn

What is @npmcli/promise-spawn?

The @npmcli/promise-spawn package is designed to execute shell commands or scripts with a promise-based interface. It simplifies working with child processes in Node.js by providing a straightforward way to spawn processes and handle their output, errors, and exit codes asynchronously. This package is particularly useful for building Node.js applications that need to interact with the system's shell or execute external commands as part of their operation.

What are @npmcli/promise-spawn's main functionalities?

Executing a simple command

This feature allows you to execute a simple command (in this case, 'echo') and print its output, error output, and exit code. The 'stdioString' option is used to treat the output and error as strings.

const promiseSpawn = require('@npmcli/promise-spawn');

async function runCommand() {
  const { stdout, stderr, code } = await promiseSpawn('echo', ['Hello, world!'], { stdioString: true });
  console.log(`Output: ${stdout}`);
  console.error(`Error: ${stderr}`);
  console.log(`Exit code: ${code}`);
}

runCommand();

Executing a command with error handling

This feature demonstrates executing a command that is expected to fail (attempting to list a nonexistent directory) and handling the error gracefully. The catch block captures the error, allowing the application to respond appropriately.

const promiseSpawn = require('@npmcli/promise-spawn');

async function runCommandWithErrorHandling() {
  try {
    const { stdout } = await promiseSpawn('ls', ['-l', '/nonexistent'], { stdioString: true });
    console.log(`Output: ${stdout}`);
  } catch (err) {
    console.error(`Error: ${err.message}`);
  }
}

runCommandWithErrorHandling();

Other packages similar to @npmcli/promise-spawn

execa

Execa is a popular alternative to @npmcli/promise-spawn for executing shell commands. It offers a richer API, including support for synchronous execution, better Windows support, and more detailed control over the child process. Compared to @npmcli/promise-spawn, execa might be preferred for more complex use cases requiring these additional features.

child-process-promise

Child-process-promise provides promise-based wrappers for the Node.js child_process module functions. Similar to @npmcli/promise-spawn, it simplifies working with child processes by returning promises. However, it sticks closer to the original Node.js API, making it a good choice for those who prefer a minimal abstraction layer.

README

@npmcli/promise-spawn

Spawn processes the way the npm cli likes to do. Give it some options, it'll give you a Promise that resolves or rejects based on the results of the execution.

USAGE

const promiseSpawn = require('@npmcli/promise-spawn')

promiseSpawn('ls', [ '-laF', 'some/dir/*.js' ], {
  cwd: '/tmp/some/path', // defaults to process.cwd()
  stdioString: true, // stdout/stderr as strings rather than buffers
  stdio: 'pipe', // any node spawn stdio arg is valid here
  // any other arguments to node child_process.spawn can go here as well,
}, {
  extra: 'things',
  to: 'decorate',
  the: 'result',
}).then(result => {
  // {code === 0, signal === null, stdout, stderr, and all the extras}
  console.log('ok!', result)
}).catch(er => {
  // er has all the same properties as the result, set appropriately
  console.error('failed!', er)
})

API

promiseSpawn(cmd, args, opts, extra) -> Promise

Run the command, return a Promise that resolves/rejects based on the process result.

Result or error will be decorated with the properties in the extra object. You can use this to attach some helpful info about why the command is being run, if it makes sense for your use case.

If stdio is set to anything other than 'inherit', then the result/error will be decorated with stdout and stderr values. If stdioString is set to true, these will be strings. Otherwise they will be Buffer objects.

Returned promise is decorated with the stdin stream if the process is set to pipe from stdin. Writing to this stream writes to the stdin of the spawned process.

Options

• stdioString Boolean, default true. Return stdout/stderr output as strings rather than buffers.
• cwd String, default process.cwd(). Current working directory for running the script. Also the argument to infer-owner to determine effective uid/gid when run as root on Unix systems.
• shell Boolean or String. If false, no shell is used during spawn. If true, the system default shell is used. If a String, that specific shell is used. When a shell is used, the given command runs from within that shell by concatenating the command and its escaped arguments and running the result. This option is not passed through to child_process.spawn.
• Any other options for child_process.spawn can be passed as well.

promiseSpawn.open(arg, opts, extra) -> Promise

Use the operating system to open arg with a default program. This is useful for things like opening the user's default browser to a specific URL.

Depending on the platform in use this will use start (win32), open (darwin) or xdg-open (everything else). In the case of Windows Subsystem for Linux we use the default win32 behavior as it is much more predictable to open the arg using the host operating system.

Options

Options are identical to promiseSpawn except for the following:

• command String, the command to use to open the file in question. Default is one of start, open or xdg-open depending on platform in use.

Changelog

8.0.0 (2024-09-03)

⚠️ BREAKING CHANGES

• @npmcli/promise-spawn now supports node ^18.17.0 || >=20.5.0

Bug Fixes

• eeaf662 #122 align to npm 10 node engine range (@hashtagchris)

Chores

• 392dc76 #122 run template-oss-apply (@hashtagchris)
• 9ed7cbe #120 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (@dependabot[bot])
• 63cc0e6 #121 postinstall for dependabot template-oss PR (@hashtagchris)
• a784586 #121 bump @npmcli/template-oss from 4.23.1 to 4.23.3 (@dependabot[bot])