just-run-it

A simple and straightforward javascript library for running system commands.

Warning: This is a package I wrote to serve my needs on a few different projects: it's manually tested, but there's not much (or anything) in the way of automated testing, so best of luck to you. Please file issues if you find any, I'll do my best to address them.

Overview

This is a slightly opinionated and not terribly flexible wrapper around Node's child_process.spawn function, which makes it simple to run commands, capture output, stream output, and handle errors, as long as you don't need a lot of flexibility. If you need more flexibility, definitely just use spawn.

Installation

npm install --save just-run-it

Basic usage

const runIt = require("just-run-it");

const { stdout, stderr, code } = await runIt(["node", "--version"]);

Quick Features

If you like these features, awesome. If not, a few of them can be disabled, otherwise use child_process.spawn directly.

• Streams command's STDOUT and STDERR to your own process's (disable with quiet option).
• Captures STDOUT and STDERR to strings for your use (disable with capture option).
• Fails (rejects) if command fails to execute, or terminates with non-zero exit code.
• Fails (rejects) if command is terminated with unhandled signal.
• Optionally connect a readable Stream object to command's STDIN.
• Forwards SIGTERM and SIGINT from child process to calling process (disable with trapSignals option).
• Not processed through the shell (no escaping required).

API and Options

The package exports a single function which returns a Promise and has with the following signature:

runIt(args, [options]);

The args parameter is an array of strings giving all of the arguments for the child process, starting with the command itself (this is different from spawn, which takes the command separate from it's parameters).

The options is parameter is an optional Object you can use to configure a few things.

Options

Return Value

The function returns a Promise which fulfills with an Object. By default (when capture is enabled), the Object has the following properties:

| Property Name | Description | | ------------- | ----------------------------------------------------------------------------------------------- | | code | The exit code of the command, which will always be 0 because otherwise the Promise will reject. | | stdout | The captured output from the command process's STDOUT stream, as a string. | | stderr | The captured output from the command process's STDERR stream, as a string. |

If the capture option is false, then the stdout and stderr properties will not be defined.

Errors

The Promise returned by the function will reject under any of the following conditions:

1. The command child process fails to start, i.e., the ChildProcess fires an "error" event.
2. The command process exits with a non-zero exit code.
3. The command process is killed by a signal.

In all cases, the Error that the promise rejects with has the following properties:

| Error property | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | command | The first element from the given args, representing the command that was executed, in isolation from it's parameters. | | args | The remaining elements of args, representing the parameters passed to the command. | | shellCommand | A "pretty" string representing the command as it might be invoked in the shell. This is only meant for human consumption, no guarantees are made as to the accuracy of the syntax. | | stdout | The captured STDOUT from the command, or null if capture is disabled | | stderr | The captured STDERR from the command, or null if capture is disabled |

In the event that the process fails to start (condition 1, above) the Error will also have a cause property which is the original Error fired by the ChildProcess. In this case the stack property of the Error issued by this function has been augmented with the stack of the causing error.

In the event that the command exits with a non-zero exit code (condition 2, above), the Error will have a code property containing the exit code of the process.

Lastly, if the command is killed by a signal before it exits (condition 3, above), the Error will have a signal property set to the name of the signal that killed the process.

Colorization

By default, the color option (see above) is set to true, which will attempt to load a terminal color library from this packages optional dependencies. Any of the following packages will be loaded if available (in order of priority, for no particular reason):

1. ansi-colors
2. colorette
3. chalk
4. kleur

If none of these packages are available, the default colorizer will simply pass through strings untransformed.

You can also provide your own colorization object to the color option, which provides a set of prescribed methods. Each method should be a string transformation, meaning a function that takes a string and returns a string. Note that the function will be applied to arbitrarily small chunks of the stream data from the command child process, not necessarily seeing the entire string at one time.

A colorization object (referred to as c, below) should provide the following string transformation methods:

| Method Name | Used for | Fallbacks | | ----------- | ------------------------------------------------------------------------ | ------------------------------- | | prompt | The leading "> " before the "shell command" at the start of the command. | c.command, c.gray, c.grey | | command | The "shell command" that is printed when the command is initialized | c.gray, c.grey | | stdout | Used to colorize everything from the command process's STDOUT stream | c.green | | stderr | Used to colorize everything from the command process's STDERR stream | c.red |

Any methods that are missing will attempt to use the fallback methods as listed, in order. If none of fallbacks are available either, the method from the default colorizer is used.