# @bconnorwhite/exec

> Execute commands while keeping flags easily configurable as an object

Latest version **6.0.12** (published 2023-01-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @bconnorwhite/exec
pnpm add @bconnorwhite/exec
yarn add @bconnorwhite/exec
bun add @bconnorwhite/exec
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.0.12 |
| Published | 2023-01-01 |
| First published | 2020-03-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 28.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Connor White |
| Maintainers | bconnorwhite |
| Keywords | exec, spawn, run, execute, parallel, concurrent, shell, flags |

## Links

- npm: https://www.npmjs.com/package/@bconnorwhite/exec
- Repository: https://github.com/bconnorwhite/exec
- Homepage: https://connorwhite.org/github/exec
- npm.io page: https://npm.io/package/@bconnorwhite/exec

## Dependencies (5)

- [strip-ansi](https://npm.io/package/strip-ansi.md) 6.0.0
- [cross-spawn](https://npm.io/package/cross-spawn.md) ^7.0.3
- [as-typed-array](https://npm.io/package/as-typed-array.md) ^1.0.0
- [extract-first-json](https://npm.io/package/extract-first-json.md) ^1.0.1
- [terminating-newline](https://npm.io/package/terminating-newline.md) ^1.2.4

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 6.0.12 (latest) — 2023-01-01
- 6.0.11 — 2022-01-17
- 6.0.10 — 2021-08-14
- 6.0.9 — 2021-07-12
- 6.0.8 — 2021-06-26
- 6.0.7 — 2021-04-01
- 6.0.6 — 2020-09-25
- 6.0.5 — 2020-09-21
- 6.0.4 — 2020-09-21
- 6.0.3 — 2020-09-21
- 6.0.2 — 2020-09-20
- 6.0.1 — 2020-09-20
- 6.0.0 — 2020-09-20
- 5.3.2 — 2020-09-15
- 5.3.1 — 2020-09-10
- … 23 more at https://npm.io/package/@bconnorwhite/exec/versions

## README

<div align="center">
  <h1>@bconnorwhite/exec</h1>
  <a href="https://npmjs.com/package/@bconnorwhite/exec">
    <img alt="npm" src="https://img.shields.io/npm/v/@bconnorwhite/exec.svg">
  </a>
  <a href="https://github.com/bconnorwhite/bob">
    <img alt="typescript" src="https://img.shields.io/github/languages/top/bconnorwhite/bob.svg">
  </a>
  <a href="https://coveralls.io/github/bconnorwhite/exec?branch=master">
    <img alt="Coveralls Status" src="https://img.shields.io/coveralls/github/bconnorwhite/exec.svg?branch=master">
  </a>
  <a href="https://github.com/bconnorwhite/exec">
    <img alt="GitHub stars" src="https://img.shields.io/github/stars/bconnorwhite/exec?label=Stars%20Appreciated%21&style=social">
  </a>
  <a href="https://twitter.com/bconnorwhite">
    <img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/bconnorwhite.svg?label=%40bconnorwhite&style=social">
  </a>
</div>

<br />

> 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](#exec)  
- [execSync](#execsync)  
- [execAll](#execall)  
- [executableToString](#executabletostring)

<br />

### exec

#### 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<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
}
```

<br />

### execSync

#### 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
```
### Types
```ts
function execSync(command: string, args: Args, { env, silent }: Options): ExecResult;
function execSync({ command, args, env, silent }: Executable): ExecResult;

```

<br />

### execAll

#### 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<ExecResult[]>;

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

<br />

### executableToString

#### 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;
}
```

<br />

<h2>Dependencies<img align="right" alt="dependencies" src="https://img.shields.io/david/bconnorwhite/exec.svg"></h2>

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

<br />

<h2>Dev Dependencies<img align="right" alt="David" src="https://img.shields.io/david/dev/bconnorwhite/exec.svg"></h2>

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

<br />

<h2>License <img align="right" alt="license" src="https://img.shields.io/npm/l/@bconnorwhite/exec.svg"></h2>

[MIT](https://mit-license.org/)

---
_Source: https://npm.io/package/@bconnorwhite/exec · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._