@jsdevtools/ez-spawn

What is @jsdevtools/ez-spawn?

@jsdevtools/ez-spawn is an npm package that simplifies the process of spawning child processes in Node.js. It provides a straightforward API for running shell commands and handling their output, errors, and exit codes.

What are @jsdevtools/ez-spawn's main functionalities?

Running Shell Commands

This feature allows you to run shell commands and capture their output. The example demonstrates running the 'echo' command and logging its output.

const { spawn } = require('@jsdevtools/ez-spawn');

spawn('echo', ['Hello, World!'])
  .then(result => {
    console.log(result.stdout); // Outputs: Hello, World!
  })
  .catch(err => {
    console.error(err);
  });

Handling Errors

This feature allows you to handle errors that occur when running shell commands. The example demonstrates attempting to run a nonexistent command and catching the resulting error.

const { spawn } = require('@jsdevtools/ez-spawn');

spawn('nonexistent-command')
  .then(result => {
    console.log(result.stdout);
  })
  .catch(err => {
    console.error('Command failed:', err.message);
  });

Capturing Exit Codes

This feature allows you to capture the exit code of a shell command. The example demonstrates running a Node.js script that exits with code 1 and logging the exit code.

const { spawn } = require('@jsdevtools/ez-spawn');

spawn('node', ['-e', 'process.exit(1)'])
  .then(result => {
    console.log('Exit code:', result.exitCode); // Outputs: Exit code: 1
  })
  .catch(err => {
    console.error(err);
  });

Other packages similar to @jsdevtools/ez-spawn

child_process

The 'child_process' module is a built-in Node.js module that provides the ability to spawn child processes. It offers more flexibility and control compared to @jsdevtools/ez-spawn but requires more boilerplate code to handle common tasks like capturing output and handling errors.

execa

Execa is a popular npm package for executing shell commands in Node.js. It provides a promise-based API similar to @jsdevtools/ez-spawn but includes additional features like improved cross-platform support and better handling of subprocesses.

shelljs

ShellJS is an npm package that provides Unix shell commands for Node.js. It allows you to run shell commands and scripts with a simple API. While it offers more comprehensive shell command support, it is not as focused on spawning child processes as @jsdevtools/ez-spawn.

README

EZ Spawn

Simple, consistent process spawning

Features

• Flexible input parameters
  Pass the program and arguments as a single string, an array of strings, or as separate parameters.

• Pick your async syntax
  Supports Promises, async/await, or callbacks.

• Simple, consistent error handling
  Non-zero exit codes are treated just like any other error. See Error Handling for more details.

• String output by default
  stdout and stderr output is automatically decoded as UTF-8 text by default. You can set the encoding option for a different encoding, or even raw binary buffers.

• Windows Support
  Excellent Windows support, thanks to cross-spawn.

Related Projects

• chai-exec - Chai assertion plugin for testing CLIs

Examples

const ezSpawn = require('@jsdevtools/ez-spawn');

// These are all identical
ezSpawn.sync(`git commit -am "Fixed a bug"`);           // Pass program and args as a string
ezSpawn.sync("git", "commit", "-am", "Fixed a bug");    // Pass program and args as separate params
ezSpawn.sync(["git", "commit", "-am", "Fixed a bug"]);  // Pass program and args as an array
ezSpawn.sync("git", ["commit", "-am", "Fixed a bug"]);  // Pass program as a string and args as an array

// Make a synchronous call
let process = ezSpawn.sync(`git commit -am "Fixed a bug"`);
console.log(process.stdout);

//Make an asynchronous call, using async/await syntax
let process = await ezSpawn.async(`git commit -am "Fixed a bug"`);
console.log(process.stdout);

//Make an asynchronous call, using callback syntax
ezSpawn.async(`git commit -am "Fixed a bug"`, (err, process) => {
  console.log(process.stdout);
});

//Make an asynchronous call, using Promise syntax
ezSpawn.async(`git commit -am "Fixed a bug"`)
  .then((process) => {
    console.log(process.stdout);
  });

Installation

Install using npm:

npm install @jsdevtools/ez-spawn

Then require it in your code:

// Require the whole package
const ezSpawn = require("@jsdevtools/ez-spawn");

// Or require "sync" or "async" directly
const ezSpawnSync = require("@jsdevtools/ez-spawn").sync;
const ezSpawnAsync = require("@jsdevtools/ez-spawn").async;

API

ezSpawn.sync(command, [...arguments], [options])

Synchronously spawns a process. This function returns when the proecess exits.

• The command and arguments parameters can be passed as a single space-separated string, or as an array of strings, or as separate parameters.

• The options object is optional.

• Returns a Process object

ezSpawn.async(command, [...arguments], [options], [callback])

Asynchronously spawns a process. The Promise resolves (or the callback is called) when the process exits.

• The command and arguments parameters can be passed as a single space-separated string, or as an array of strings, or as separate parameters.

• The options object is optional.

• If a callback is provided, then it will be called when the process exits. The first is either an Error or null. The second parameter is a Process object.

• If no callback is provided, then a Promise is returned. It will resolve with a Process object when the process exits.

Options object

ezSpawn.async() and ezSpawn.sync() both accept an optional options object that closely mirrors the options parameter of Node's spawn, exec, spawnSync, and execSync functions.

• cwd (string)
  The current working directory of the child process.

• env (Object)
  Environment variable key-value pairs.

• argv0 (string)
  Explicitly set the value of argv[0] sent to the child process. This will be set to command if not specified.

• stdio (Array or string)
  The child process's stdio configuration (see options.stdio).

• input (string, Buffer, TypedArray, or DataView)
  The value which will be passed as stdin to the spawned process. Supplying this value will override stdio[0].

• uid (number)
  Sets the user identity of the process.

• gid (number)
  Sets the group identity of the process.

• timeout (number)
  The maximum amount of time (in milliseconds) the process is allowed to run.

• killSignal (string or integer)
  The signal value to be used when the spawned process will be killed. Defaults to "SIGTERM".

• maxBuffer (number)
  The largest amount of data in bytes allowed on stdout or stderr. If exceeded, the child process is terminated.

• encoding (string)
  The encoding used for all stdio inputs and outputs. Defaults to "utf8". Set to "buffer" for raw binary output.

• shell (boolean or string)
  If true, then command will be run inside of a shell. Uses "/bin/sh" on UNIX, and process.env.ComSpec on Windows. A different shell can be specified as a string.

• windowsVerbatimArguments (boolean)
  No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is "CMD".

• windowsHide (boolean)
  Hide the subprocess console window that would normally be created on Windows systems.

Process object

ezSpawn.async() and ezSpawn.sync() both return a Process object that closely mirrors the object returned by Node's spawnSync function.

• command (string)
  The command that was used to spawn the process.

• args (array of strings)
  The command-line arguments that were passed to the process.

• pid (number)
  The numeric process ID assigned by the operating system.

• stdout (string or Buffer)
  The process's standard output. This is the same value as output[1].

• stderr (string or Buffer)
  The process's error output. This is the same value as output[2].

• output (array of strings or Buffers)
  The process's stdio [stdin, stdout, stderr].

• status (number)
  The process's status code (a.k.a. "exit code").

• signal (string or null)
  The signal used to kill the process, if the process was killed by a signal.

• toString()
  Returns the command and args as a single string. Useful for console logging.

Error Handling

All sorts of errors can occur when spawning processes. Node's built-in spawn and spawnSync functions handle different types of errors in different ways. Sometimes they throw the error, somtimes they emit an "error" event, and sometimes they return an object with an error property. They also don't treat non-zero exit codes as errors. So it's up to you to handle all these different types of errors, and check the exit code too.

EZ Spawn simplifies things by treating all errors the same. If any error occurs, or if the process exits with a non-zero exit code, then an error is thrown. The error will have all the same properties as the Process object, such as status, stderr, signal, etc.

try {
  let process = ezSpawn.sync(`git commit -am "Fixed a bug"`, { throwOnError: true });
  console.log("Everything worked great!", process.stdout);
}
catch (error) {
  console.error("Something went wrong!", error.status, error.stderr);
}

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

1. Clone this repo
   git clone hhttps://github.com/JS-DevTools/ez-spawn.git

2. Install dependencies
   npm install

3. Run the tests
   npm test

License

EZ Spawn is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤