command-promise
v2.0.1
Published
Promise wrapper for child_process.exec.
Downloads
415
Maintainers
Readme
Command
Promise & stream wrapper around child_process.exec
. Uses promise for result, but if there is a Q or Bluebird will switch to it. This lib also handles arrays smartly, so not need in manual constructing any apply
-ing them.
Module can be bundled: all deps melted into, without node_modules/
size is reduced to ~80kB.
usage
// Command return promise
Command('ls -1').then(console.log, console.error)
// Process return duplex stream with writable as stdin,
// and readable as stdout for spawned subprocess
Process('ls -1').pipe(process.stdout)
Process('ls -1').pipe(Process('xargs file -b')).pipe(process.stdout)
signature
// Command(…) → Promise
// promise's value is `[ String(stdout), String(stderr) ]`
Command(chunk)
Command(chunk, options)
Command(chunk, chunk, ...)
Command(chunk, chunk, ..., options)
Command(chunk, chunk, ..., options, options)
Command(chunk, chunk, ..., options, chunk, options)
Command(<any sequence of chunks and options>)
// Process(…) → Stream (is duplex)
// duplex input is subprocess stdin
// duplex output is subprocess stdout
Process(chunk)
Process(chunk, options)
Process(chunk, chunk, ...)
Process(chunk, chunk, ..., options)
Process(chunk, chunk, ..., options, options)
Process(chunk, chunk, ..., options, chunk, options)
Process(<any sequence of chunks and options>)
options is a object of options for child_process.exec
.
chunk is a string or array of strings or arguments or array of strings and options.
All chunks are concatenated in one flat array, options objects are merged in one as well.
If you have hardcoded data just pass strings. If you have variative data then pass arrays, no need in joining elements or manipulating with .apply
. If all of your data is hardcoded, look at Command.Simple.
The executed command can be complex, contain pipes and shell stream redirections.
Command utils
There're some utils to transform Command's result:
only stdout: If you want command to return only stdout, use util.stdout
:
Command('ls -l').then(Command.util.stdout)
This will return not pair, but stdout
string only.
stderr as error: By default, result promise will be rejected only if child_process.exec
returns error. It happens when return code is non-zero. If you want to reject also if there is something in stderr
, use util.stderr
. If no error, this will return stdout
string only.
trim content: The majority of shell commands return streams with newline at the end. You can use util.trim
to trim both stdout
and stderr
. It also works with string only, if promise was converted by util.stdout
earlier.
examples
Command('ls', '-lA', { cwd: '/tmp' }).then(...)
Command('ls', [ '-l', '-A' ], { cwd: '/tmp' }).then(...)
Command('ls', [ '-l', '-A', { cwd: '/tmp' } ]).then(...)
Command([ 'ls', '-1' ], { cwd: '/tmp' }).then(...)
function Echo () { return Command('echo', '-', arguments); }
Echo('-n', '-a', '-b', { encoding: 'ascii' }).then(...)
Process('find src -name "*.js"').pipe(Process('xargs cat')).pipe(process.stdout)
// or just
Process('find src -name "*.js"', '|', 'xargs cat').pipe(process.stdout)
simple command
If you don't need any advanced arguments features, you can use Command.Simple
& Process.Simple
.
Command.Simple(str)
Command.Simple(str, options)
Process.Simple(str)
Process.Simple(str, options)
using in the mid of the promise flow
Use Command.so
it creates function which will self invoke command.
It does not append any arguments to command, so it can be used to order operations.
Command('mkdir -p build')
.then(Command.so('cp package.json build/'))
.then(Command.so('cp -r src/'))
.then(...);
using in partials
var gitLog = partial(Command, 'git', 'log', { cwd: '/opt/repo' });
var gitLogOneline = partial(gitLog, '--oneline');
gitLogOneline().then(console.log, console.error);
gitLogOneline('-15').then(console.log, console.error);
using in pipes
Use Process
in pipes, as a cheap and clear analogue of Gulp/Vinyl streams.
var proc = require('command-promise/Process')
var write = require('fs').createWriteStream
gulp.task('less', function ()
{
return proc('lessc', './web/css/index.less')
.pipe (proc('postcss --use autoprefixer'))
.pipe(write('index.css'))
})
Process
produces regular (not vinyl-fs
) duplex streams. So you can use any commands in your pipes (even if they have no adapters for Gulp). Since Gulp can work with regular streams, you can use Process
inside Gulp tasks.
license
MIT. © StreetStrider, 2014 — 2015.