@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
• Easily extract JSON output
• Inject environment variables
• Set silent to block CLI output

Installation

yarn add @bconnorwhite/exec

npm install @bconnorwhite/exec

API

• exec
• execSync
• execAll
• executableToString

exec

Usage

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

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

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
}

execSync

Usage

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

Types

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

execAll

Usage

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

function execAll(
  executables: Executable[],
  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;
}

executableToString

Usage

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

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