terminal-spawn
A library which wraps Node's child_process.spawn
to provide easy use of terminal commands.
It does this in an easy to use way by providing a nice interface on top of
child_process.spawn
which allows you to call it exactly the same way as
if you were running commands directly in the terminal.
I personally use this for running gulp tasks,
since I got used to using npm scripts and their ability to directly run terminal
commands very easily. Since it returns a Promise<SpawnSyncReturns<Buffer>>
,
it can be directly used in gulp,
see the gulpfile.babel.ts
in this project for an example.
This project uses TypeScript and thus has types for it exported,
so it works well in that environment. However, it also works just fine with
vanilla JavaScript.
Installation
npm install terminal-spawn
Usage
To just spawn a task if you don't need to know when it finishes
import terminalSpawn from 'terminal-spawn';
terminalSpawn('echo "hello world!"');
To spawn a task and wait for it to complete, checking status code
import terminalSpawn from 'terminal-spawn';
(async () => {
const subprocess = await terminalSpawn('echo "hello world!"');
if (subprocess.status === 0) {
console.log('everything went well!');
} else {
console.warn('something went wrong!!!!');
}
})();
API
terminalSpawn(command, options)
return type: Promise<SpawnSyncReturns<Buffer>>
Executes the command inside of Node.js as if it were run in the shell. If
command is an array then the commands will be run in series/sequentially.
The result is a Promise
which has the same structure/type as the
return value of the synchronous version of child_process.spawn
.
terminalSpawnParallel(command, options)
return type: Promise<SpawnSyncReturns<Buffer>>
Executes the command inside of Node.js as if it were run in the shell, if
command is an array then the commands will be run in parallel rather than
in series/sequentially.
The result is a Promise
which has the same structure/type as the
return value of the synchronous version of child_process.spawn
.
command
type: string
or string[]
The command will be run using the shell and the output will be redirected to the shell.
This means that it will essentially function as if you ran it directly in a
shell such as /bin/sh
, but inside of Node.js.
If command is an array then all of the commands in the array will be executed:
either in series or in parallel, depending on the function. The default is to
executed them in series, as if they were called with &&
between them.
options
type: SpawnOptions
These are the options to pass to child_process.spawn
they are the same as the spawn
options
and are passed directly to child_process.spawn
.
By default they are:
{
stdio: 'inherit',
shell: true,
}
The API for options is designed to be as user-friendly as possible thus,
it assumes that you want to keep the terminal-like behavior, but may want
to change other options such as using cwd
. To support this the user-provided
options are added to the default options, rather than always overwriting them
(aka. set union). However, if you explicitly specify a a default command such
as stdio
then it will be overwritten.
Which allows terminalSpawn
to act like a terminal. However, if you wanted the
nice argument passing of terminalSpawn, e.g. 'echo "hello world!"
without
actually using the terminal, then you could disable this using options
.
However, it should be noted that if you pass the option shell: false
then
many features such as multiple commands run in series or parallel will not work
due to reliance on running in a shell.
License
MIT Copyright (c) David Piper