@bconnorwhite/exec

@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
• Inject environment variables
• Set silent to ignore output

Installation

yarn add @bconnorwhite/exec

npm install @bconnorwhite/exec

API

• exec
• execSync
• execAll
• flagsToArgs
• commandToString

exec

Usage

import exec from "@bconnorwhite/exec";

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

// Object usage:
exec({
  command: "babel",
  args: "./src", // for multiple args, use an array instead
  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

function exec(command: string, args: Args, flags: Flags, { env, silent }: Options): Promise<ExecResult>;
function exec({ command, args, flags, env, silent }: Command): Promise<ExecResult>;

type Command = {
  command: string;
  args?: string | string[];
  flags?: Flags;
  cwd?: string;
  env?: NodeJS.ProcessEnv;
  silent?: boolean;
}

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

type ExecResult = {
  error: string;
  output: string;
  colorError: string;
  colorOutput: string;
  jsonOutput: () => JSONObject | undefined;
  jsonError: () => JSONObject | undefined;
}

execSync

Usage

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

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

// Object usage:
execSync({
  command: "babel",
  args: "./src", // for multiple args, use an array instead
  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

function execSync(command: string, args: Args, flags: Flags, { env, silent }: Options): ExecResult;
function execSync({ command, args, flags, env, silent }: Command): ExecResult;

execAll

Usage

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

execAll([{
  command: "babel",
  args: ["./src"],
  flags: {
    "out-dir": "./build",
    "config-file": "./babel.config.json",
    "watch": true
  }
}, {
  command: "tsc",
  flags: {
    "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

function execAll(
  commands: Command[],
  options: ExecAllOptions
): Promise<ExecResult[]>;

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

flagsToArgs

Usage

import { flagsToArgs } from "@bconnorwhite/exec";

flagsToArgs({
  "out-dir": "./build",
  "config-file": "./babel.config.json",
  "watch": true
});
// ["--out-dir", "./build", "--config-file", "./babel.config.json", "--watch"]

Types

function flagsToArgs(flags?: Flags): string[];

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

flagsToArgs is useful for adding flags that must preceed later arguments. For example:

import { flagsToArgs } from "@bconnorwhite/exec";

const files = [...];

exec({
  command: "wc",
  args: flagsToArgs({ l: true }).concat(files)
});
// Equivalent of:
// wc -l [FILES]...

commandToString

Usage

import { commandToString } from "@bconnorwhite/exec";

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

Types

function commandToString(command: Command): string;

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

Dependencies

• 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/node: TypeScript definitions for Node.js
• coveralls: Takes json-cov output into stdin and POSTs to coveralls.io
• jest: Delightful JavaScript Testing.

License

MIT