@bconnorwhite/exec

> Execute commands while keeping flags easily configurable as an object.

- Run one or multiple commands in parallel or series
- Easily define arguments and flags
- Easily extract JSON output
- Inject environment variables
- Set silent to block CLI output

Installation

``bash
yarn add @bconnorwhite/exec
`

`bash
npm install @bconnorwhite/exec
`

API

- exec
- execSync
- execAll
- executableToString

$3

#### Usage

`js
import { exec } from "@bconnorwhite/exec";

// Simple usage:
exec("echo", "hello");

// Explicit usage:
exec({
command: "babel",
args: [
"./src",
{ // Objects are used for flags
"out-dir": "./build",
"config-file": "./babel.config.json",
"w": true // single character flags will be set using a single dash
}
]
});

// Equivalent of:
// babel ./src --out-dir ./build --config-file ./babel.config.json -w
`

#### Types

`ts
function exec(command: string, args: Args, { env, silent }: Options): Promise;
function exec({ command, args, env, silent, cwd }: Executable): Promise;

type Executable = {
command: string;
args?: Args;
cwd?: string;
env?: NodeJS.ProcessEnv;
silent?: boolean;
}

type Args = Arg | Arg[];

type Arg = string | Flags;

type Flags = {
[flag: string]: string | number | boolean | string[] | undefined;
}

type ExecResult = {
output: string;
error: string;
textOutput: string; // output stripped on ANSI colors
textError: string; // error stripped on ANSI colors
jsonOutput: () => JSONObject | JSONArray | undefined; // First JSON object or array in output
jsonError: () => JSONObject | JSONArray | undefined; // First JSON object or array in error
}
`

$3

#### Usage

`js
import { execSync } from "@bconnorwhite/exec";

// Simple usage:
execSync("echo", "hello");

// Object usage:
execSync({
command: "babel",
args: [
"./src",
{ // Objects are used for flags
"out-dir": "./build",
"config-file": "./babel.config.json",
"w": true // single character flags will be set using a single dash
}
]
});

// Equivalent of:
// babel ./src --out-dir ./build --config-file ./babel.config.json -w
`


$3

`

$3

#### Usage

`js
import { execAll } from "@bconnorwhite/exec";

execAll([{
command: "babel",
args: [
"./src",
{ // Objects are used for flags
"out-dir": "./build",
"config-file": "./babel.config.json",
"w": true // single character flags will be set using a single dash
}
]
}, {
command: "tsc",
args: {
"emitDeclarationOnly": true
}
}], {
env: {
NODE_ENV: "development"
},
parallel: false
});
// Equivalent of:
// NODE_ENV=development babel ./src --out-dir ./build --config-file ./babel.config.json --watch && tsc --emitDeclarationOnly
`
#### Types
`ts
function execAll(
executables: Executable[],
options: ExecAllOptions
): Promise;

type ExecAllOptions = {
cwd?: string;
env?: NodeJS.ProcessEnv; // default, will not override individual commands
silent?: boolean; // default, will not override individual commands
parallel?: boolean;
}
`

$3

#### Usage

`js
import { executableToString } from "@bconnorwhite/exec";

executableToString({
command: "foo",
args: [
"a",
"b",
{
c: true,
d: "ok",
long: true
}
]
});
// "foo a b -c -d ok --long"
`

#### Types

`ts
function executableToString(command: Executable): string;

type Executable = {
command: string;
args?: string | string[];
flags?: Flags;
env?: NodeJS.ProcessEnv;
}
``

Dependencies

- as-typed-array: Make any value an array, and maintain types
- cross-spawn: Cross platform child_process#spawn and child_process#spawnSync
- parse-json-object: Parse a typed JSON object.
- strip-ansi: Strip ANSI escape codes from a string
- terminating-newline: Add or remove a terminating newline

Dev Dependencies

- @bconnorwhite/bob: Bob builds and watches typescript projects.
- @types/cross-spawn: TypeScript definitions for cross-spawn
- @types/node: TypeScript definitions for Node.js
- coveralls: Takes json-cov output into stdin and POSTs to coveralls.io
- jest: Delightful JavaScript Testing.

License

MIT