EZ Spawn

Simple, consistent, cross-platform process spawning

EZ-Spawn

Simple, consistent process spawning

Cross-Platform Compatibility Build Status

Coverage Status Dependencies

npm License

Features

Examples

const ezSpawn = require('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 ez-spawn

Then require it in your code:

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

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

API

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

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

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

Asynchronously spawns a process. The Promise resolves (or the callback is called) 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.

Process object

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

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! File 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.

Big Thanks To

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

Travis CI SauceLabs Coveralls