CommandQueue
CommandQueue provides a flexible API for executing groups of commands synchronously or asynchronously. It was originally created to provide an alternative to using the scripts field in package.json for executing commands. By using CommandQueue, you can easily execute commands from a JavaScript file instead, which is better suited for managing complex build steps.
Table of Contents
Features
- Supports different combinations of synchronous and asynchronous command execution.
- Allows full customization of child_process parameters for executing a command.
Installation
To install the package:
npm install command-queue
To require the package:
var CommandQueue = ;
Usage
Synchronous Execution
To specify the commands to run synchronously, use the .sync()
method:
// Update the PATH if necessary.processenvPATH += ':./node_modules/.bin'; ;
Asynchronous Execution
To specify the commands to run asynchronously, use the .async()
method:
;
Parallel Execution
To specify the commands to run in parallel, use the .parallel()
method:
;
Parallel execution runs the commands asynchronously, but if one fails, the remaining commands are terminated using SIGTERM.
Note: This functionality is inspired by Parallel Shell.
Nested Execution
CommandQueue itself can be used as a command:
;
Batched Execution
Each call to an .async()
, .sync()
, or .parallel()
method creates a
new batch of commands. CommandQueue waits for the current batch of commands
to complete before executing the next batch of commands.
In the following example, CommandQueue waits for the A commands to complete before executing the B commands, and waits for the B commands to complete before executing the C commands.
;
Run
To start command execution, use the .run()
method. The .run()
method
returns a deferred promise which
is resolved when the commands have completed or a command has terminated with
an error.
;
Close
To terminate currently running commands, use the .close()
method. It will send
a SIGTERM to those commands.
var queue = ; queue ;
Posix or Win32
By default CommandQueue will detect the current platform and use the appropriate
shell for executing the commands. However, you can force CommandQueue to use
a specific platform's shell by using either the .posix()
method, or
the .win32()
method.
;
;
Run Command Customization
To customize how a command is run, replace or override the
CommandQueue.prototype.runCommand()
method.
Here is the default method:
/* * Runs a command. This function is intended to be user replaceable * to allow customization of the child creation process. * * @param {string} cmd The user provided command to run. * @param {string} shell The shell commmand. * @param {string} shellFlag The shell flag. * @param {'sync'|'async'|'parallel'} runType * @returns {object} The child process. */CommandQueueprototype { var args = shellFlag cmd; var childProcess = ; return childProcess;};
By customizing the runCommand()
method, you can also change the types of
user arguments that can be passed into the .async()
, .sync()
,
and .parallel()
methods.
The following example shows how the runCommand()
method is changed to
accept a command that is an object rather than a string,
and how the .sync()
method can now be passed such an object.
var queue = ; queue { console; var args = shellFlag cmdnodeCmd; var childProcess = ; ...}; queue; queue;