@nbarray/execa
v1.0.0
Published
A better `child_process`
Downloads
4
Maintainers
Readme
execa
A better
child_process
Why
- Promise interface.
- Strips EOF from the output so you don't have to
stdout.trim()
. - Supports shebang binaries cross-platform.
- Improved Windows support.
- Higher max buffer. 10 MB instead of 200 KB.
- Executes locally installed binaries by name.
- Cleans up spawned processes when the parent process dies.
Install
$ npm install execa
Usage
const execa = require('execa');
(async () => {
const {stdout} = await execa('echo', ['unicorns']);
console.log(stdout);
//=> 'unicorns'
})();
Additional examples:
const execa = require('execa');
(async () => {
// Pipe the child process stdout to the current stdout
execa('echo', ['unicorns']).stdout.pipe(process.stdout);
// Run a shell command
const {stdout} = await execa.shell('echo unicorns');
//=> 'unicorns'
// Catching an error
try {
await execa.shell('exit 3');
} catch (error) {
console.log(error);
/*
{
message: 'Command failed: /bin/sh -c exit 3'
killed: false,
code: 3,
signal: null,
cmd: '/bin/sh -c exit 3',
stdout: '',
stderr: '',
timedOut: false
}
*/
}
})();
// Catching an error with a sync method
try {
execa.shellSync('exit 3');
} catch (error) {
console.log(error);
/*
{
message: 'Command failed: /bin/sh -c exit 3'
code: 3,
signal: null,
cmd: '/bin/sh -c exit 3',
stdout: '',
stderr: '',
timedOut: false
}
*/
}
API
execa(file, [arguments], [options])
Execute a file.
Think of this as a mix of child_process.execFile
and child_process.spawn
.
Returns a child_process
instance, which is enhanced to also be a Promise
for a result Object
with stdout
and stderr
properties.
execa.stdout(file, [arguments], [options])
Same as execa()
, but returns only stdout
.
execa.stderr(file, [arguments], [options])
Same as execa()
, but returns only stderr
.
execa.shell(command, [options])
Execute a command through the system shell. Prefer execa()
whenever possible, as it's both faster and safer.
Returns a child_process
instance.
The child_process
instance is enhanced to also be promise for a result object with stdout
and stderr
properties.
execa.sync(file, [arguments], [options])
Execute a file synchronously.
Returns the same result object as child_process.spawnSync
.
This method throws an Error
if the command fails.
execa.shellSync(file, [options])
Execute a command synchronously through the system shell.
Returns the same result object as child_process.spawnSync
.
options
Type: Object
cwd
Type: string
Default: process.cwd()
Current working directory of the child process.
env
Type: Object
Default: process.env
Environment key-value pairs. Extends automatically from process.env
. Set extendEnv
to false
if you don't want this.
extendEnv
Type: boolean
Default: true
Set to false
if you don't want to extend the environment variables when providing the env
property.
argv0
Type: string
Explicitly set the value of argv[0]
sent to the child process. This will be set to command
or file
if not specified.
stdio
Type: string[]
string
Default: pipe
Child's stdio configuration.
detached
Type: boolean
Prepare child to run independently of its parent process. Specific behavior depends on the platform.
uid
Type: number
Sets the user identity of the process.
gid
Type: number
Sets the group identity of the process.
shell
Type: boolean
string
Default: false
If true
, runs command
inside of a shell. Uses /bin/sh
on UNIX and cmd.exe
on Windows. A different shell can be specified as a string. The shell should understand the -c
switch on UNIX or /d /s /c
on Windows.
stripEof
Type: boolean
Default: true
Strip EOF (last newline) from the output.
preferLocal
Type: boolean
Default: true
Prefer locally installed binaries when looking for a binary to execute.
If you $ npm install foo
, you can then execa('foo')
.
localDir
Type: string
Default: process.cwd()
Preferred path to find locally installed binaries in (use with preferLocal
).
input
Type: string
Buffer
stream.Readable
Write some input to the stdin
of your binary.
Streams are not allowed when using the synchronous methods.
reject
Type: boolean
Default: true
Setting this to false
resolves the promise with the error instead of rejecting it.
cleanup
Type: boolean
Default: true
Keep track of the spawned process and kill
it when the parent process exits.
encoding
Type: string
Default: utf8
Specify the character encoding used to decode the stdout
and stderr
output.
timeout
Type: number
Default: 0
If timeout is greater than 0
, the parent will send the signal identified by the killSignal
property (the default is SIGTERM
) if the child runs longer than timeout milliseconds.
buffer
Type: boolean
Default: true
Buffer the output from the spawned process. When buffering is disabled you must consume the output of the stdout
and stderr
streams because the promise will not be resolved/rejected until they have completed.
maxBuffer
Type: number
Default: 10000000
(10MB)
Largest amount of data in bytes allowed on stdout
or stderr
.
killSignal
Type: string
number
Default: SIGTERM
Signal value to be used when the spawned process will be killed.
stdin
Type: string
number
Stream
undefined
null
Default: pipe
Same options as stdio
.
stdout
Type: string
number
Stream
undefined
null
Default: pipe
Same options as stdio
.
stderr
Type: string
number
Stream
undefined
null
Default: pipe
Same options as stdio
.
windowsVerbatimArguments
Type: boolean
Default: false
If true
, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to true
automatically when the shell
option is true
.
Tips
Save and pipe output from a child process
Let's say you want to show the output of a child process in real-time while also saving it to a variable.
const execa = require('execa');
const getStream = require('get-stream');
const stream = execa('echo', ['foo']).stdout;
stream.pipe(process.stdout);
getStream(stream).then(value => {
console.log('child output:', value);
});
License
MIT © Sindre Sorhus