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

Option	Default	Description
`env`	`{}`	An Object of environment variables to merge with the current process’s environment (i.e., `process.env`)
`capture`	`true`	Whether or not to capture the child process’s STDOUT and STDERR into in-memory Strings. This is done by default so they can be returned in the fulfillment value, and also used in Errors. However, if the command produces a huge amount of output that you don’t actually need, you can set this to false to save the memory.
`quiet`	`false`	The default behavior is to write the command being executed, plus STDOUT and STDERR from the child process to this process’s output streams. Set this to `true` to supress this output.
`stdin`	`process.stdin`	Optionally, provide a readable stream that will be used as the child process’s STDIN. Otherwise, this process’s STDIN is used.
`encoding`	`“utf8”`	Optionally, provide the encoding for the STDOUT and STDERR streams from the child process.
`propagateSignals`	`true`	By default, SIGINT and SIGTERM signals that terminate the child process are caught and forwarded to the parent process as well. If you set this to `false` instead, those signals will not be forwarded to the parent process.
`color`	`true`	Whether (and how) to colorize output. This is irrelevant if `quiet` is true as no output is generated. If set to `false`, the output is not colorized, it is written as is. If `true` (the default), the output is colorized using a default colorizer if available (see below). To provide a custom colorizer, provide an object with appropriate methods to transform a string into a “colorized” string, as described in the “Colorization” section, below.

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:

The command child process fails to start, i.e., the ChildProcess fires an “error” event.
The command process exits with a non-zero exit code.
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):

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.