async-exec-cmd

Simple, fast, flexible and cross-platform async executing commands (with node-cross-spawn).

Install

npm i async-exec-cmd --save
npm test

API

For more use-cases see the tests

asyncExecCmd

Async execute command via spawn. All arguments are rebuilt, merged, structured, normalized and after all passed to cross-spawn, which actually is Node's spawn.

• <cmd> {String} Command/program to execute. You can pass subcommands, flags and arguments separated with space
• [args] {Array} arguments that will be arr-union with the given in cmd. You can give opts object here instead of args
• [opts] {Object} pass options to spawn and github-short-url-regex. You can give cb function here instead of opts
• <cb> {Function} node-style callback function that will handle
  • err {Error} error if exists (instanceof Error), or null. It have some extra props:
    • command {String} the cmd plus args which was tried to execute
    • message {String} some useful message
    • buffer {Buffer} representation of the error
    • status {Number|String}
    • stack usual ... stack trace
  • res {String} representation of response for the executed command/program
    • notice when opts.stdio: 'inherit', res is empty string ''
    • notice when err, it is undefined
  • code {Number|String} e.g. 0, 1, -2, 128, 'ENOENT', etc.. Process exit status code of the execution
  • buffer {Buffer} buffer equivalent of response, e.g. <Buffer 74 75 6e 6e...>
    • notice when err, it is undefined
    • but notice you can find it again in err.buffer
• returns {Stream} child_process.spawn

Example:

var asyncExecCmd = require('async-exec-cmd')

var child = asyncExecCmd('npm install', [
  '--save-dev', 'bluebird'
], function __cb (err, res, code, buffer) {
  if (err) {
    console.error(err, code)
    return
  }

  console.log(res, code, buffer)
})

Possible signatures (will work)

these examples should work without problems

var cmd = require('async-exec-cmd')

function __cb (err, res, code, buffer) {
  if (err) {
    console.error(err, code)
    return
  }

  console.log(res, code, buffer)
}

/**
 * Try all these commands separatly or run the tests
 * they cover all situations
 */

cmd('npm', __cb)
//=> res and buffer are undefined

cmd('npm', {stdio: [null, null, null]}, __cb)
//=> err Error object, res and buffer are undefined, 

cmd('npm', ['install', '--save', 'bluebird'], __cb)
//=> err undefined, code 0, res === 'unbuild [email protected]'

cmd('npm', ['uninstall', '--save', 'bluebird'], {stdio: [null, null, null]}, __cb)
//=> err undefined, code 0, res === 'unbuild [email protected]'

cmd('npm -v', __cb)
//=> err undefined, code 0, res === '2.9.0'

cmd('npm install', ['--save', 'bluebird'], __cb)
//=> err undefined, code 0, res === '[email protected] node_modules/bluebird'

cmd('npm uninstall', ['--save', 'bluebird'], {stdio: [null, null, null]}, __cb)
//=> err  undefined, code 0, res === 'unbuild [email protected]'

cmd('npm -v', {stdio: 'inherit'}, __cb)
//=> will directly outputs: 2.9.0
//=> err undefined, code 0, res === ''

Impossible signatures (will throws/errors)

these examples should not work

cmd(__cb)
//=> first argument cant be function

cmd({ok:true})
//=> should have `callback` (non empty callback)

cmd(['--save-dev', 'bluebird'])
//=> should have `callback` (non empty callback)

cmd(['--save-dev', 'bluebird'], {ok: true})
//=> should have `callback` (non empty callback)

cmd({ok:true}, __cb)
//=> expect `cmd` be string

cmd(['--save-dev', 'bluebird'], __cb)
//=> expect `cmd` be string

cmd(['--save-dev', 'bluebird'], {ok: true}, __cb)
//=> expect `cmd` be string

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
But before doing anything, please read the CONTRIBUTING.md guidelines.

Charlike Make Reagent