executive

executive

An elegant child_process.spawn

Executive is a simple library which provides a more intuitive interface to child_process.spawn. Very useful with build tools and task runners. Async and sync command execution with built-in control flow for executing multiple commands and collecting results.

Features

• Async callback, promise and sync APIs
• Automatically pipes stderr and stdout by default
• Automatically uses shell when commands use builtins, globs or operators
• Built-in control flow with support for parallel and serial execution
• Mix simple string commands with functions and promises returning commands
• Multi-line strings parsed as multiple commands and executed sequentially
• Streams stderr and stdout rather than blocking on command completion
• No external dependencies

Install

$ npm install executive

Usage

No need to echo as stderr and stdout are piped by default.

import exec from 'executive'

exec('uglifyjs foo.js --compress --mangle > foo.min.js')

It's easy to be quiet too.

exec.quiet('uglifyjs foo.js --compress --mangle > foo.min.js')

Callbacks and promises are both supported.

exec('ls', (err, stdout, stderr) => console.log(stdout))
exec('ls').then(res => console.log(res.stdout))

Automatically serializes commands.

exec(['ls', 'ls', 'ls']) // All three ls commands will be executed in order

exec(`ls -l
      ls -lh
      ls -lha`) // Also executed in order

Want to execute your commands in parallel? No problem.

exec.parallel(['ls', 'ls', 'ls'])

Want to collect individual results? Easy.

{a, b, c} = await exec.parallel({
  a: 'echo a',
  b: 'echo b',
  c: 'echo c'
})

Want to blend in Promises or pure functions? You got it.

exec.parallel([
  'ls',

  // Promises can be blended directly in
  exec('ls'),

  // Promises returned by functions are automatically consumed
  () => exec('ls'),

  // Functions which return a string are assumed to be commands
  () => 'ls',

  // Functions and promises can return objects with stdout, stderr or status
  () => ({ stdout: 'huzzah', stderr: '', status: 0 }),

  'ls'
])

Options

Options are passed as the second argument to exec. Helper methods for quiet, interactive, parallel and sync do what you expect.

exec('ls', { options: 'quiet' })

and

exec.quiet('ls')

are equivalent.

options.interactive | exec.interactive

default false

If you need to interact with a program (your favorite text editor for instance) or watch the output of a long running process (tail -f), or just don't care about checking stderr and stdout, set interactive to true:

exec.interactive('vim', err => {
  // Edit your commit message
})

options.quiet | exec.quiet

default false

If you'd prefer not to pipe stdout and stderr set quiet to true:

exec.quiet(['ls', 'ls'], (err, stdout, stderr) => {
  // You can still inspect stdout, stderr of course
})

options.sync | exec.sync

default false

Blocking version of exec. Returns {stdout, stderr} or throws an error.

options.parallel | exec.parallel

default false

Uses parallel rather than serial execution of commands.

options.shell

default null

Force a shell to be used for command execution.

options.strict

default false

Any non-zero exit status is treated as an error. Promises will be rejected and an error will be thrown with exec.sync if syncThrows is enabled.

options.syncThrows

default false

Will cause exec.sync to throw errors rather than returning them.

Extra

Great with sake, grunt, gulp and other task runners. Even better mixed with generator-based control flow libraries and/or ES7 async/await.

Complex example using sake:

task 'package', 'Package project', ->
  # Create dist folder
  await exec '''
    mkdir -p dist/
    rm   -rf dist/*
    '''

  # Copy assets to dist
  await exec.parallel '''
    cp manifest.json dist/
    cp -rf assets/   dist/
    cp -rf lib/      dist/
    cp -rf views/    dist/
    '''

  # Get current git commit hash
  {stdout} = await exec 'git rev-parse HEAD'
  hash     = stdout.substring 0, 8

  # Zip up dist
  exec "zip -r package-#{hash}.zip dist/"

You can find more usage examples in the tests.

License

MIT