exec-plan - Run child process commands synchronously
Description
Provide the ability to run child process commands synchronously, with some fine-grained control, all while avoiding the dreaded pyramid of doom (i.e., callback indentation) >.<
Easy Install
$ sudo npm install exec-plan
Install with package.json setup
/** * package.json example * package.json should be in the root of the project that will include 'exec-plan' as a dependency. * use this method of installing 'exec-plan' module to put it under the project's local directory. */ "name": "my personal project" "version": "0.0.1" "dependencies": "exec-plan": "0.0.3"
$ sudo npm install
- Note: this will install all dependencies for "my personal project" in "node_modules" folder below the project's root directory
Examples
/** * An example of the most basic usage. */ var ExecPlan = ExecPlan;var execPlan = ; execPlan;execPlan;execPlan;execPlan;
/** * An example with more fine-grained control. */ var ExecPlan = ExecPlan;var execPlan = ; // attach event handlers to the events exposed by ExecPlanexecPlan;execPlan; // first, setup a vanilla set of commandsexecPlan;execPlan; // now, add a command that will include some 'pre logic' that will run before the command is executed, // but after previous command in the execution plan finished.execPlan; // now, add a command that will include an error handler that will run before the 'error' event is fired.execPlan; // run the set of commandsexecPlan;
/** * An example showing error-handling */var ExecPlan = ExecPlan;var execPlan = autoPrintOut: true // stdout should be automatically printed when a command is executed autoPrintErr: false // stderr should not be automatically printed to when a command has an error continueOnError: true // if an error occurs, the plan should continuing executing; execPlan; execPlan;execPlan;execPlan; execPlan;
ExecPlan API
Configuration
- The constructor takes a configuration object that dictates various behaviors of the ExecPlan. The config object has
the following properties:
- [autoPrintOut] Boolean <default: true> - whether to automatically print to stdout when a command finishes while an execution plan is executing.
- [autoPrintErr] Boolean <default: true> - whether to automatically print to stderr when a command has an error while an execution plan is executing.
- [continueOnError] Boolean <default: true> - whether to continue executing a plan if an error occurs in one of the the commands while the execution plan is executing.
- Example Usage:
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new ExecPlan({
autoPrintOut: false, // don't automatically print stdout
autoPrintErr: true, // allow stderr to be automatically printed to
continueOnError: true // if an error occurs in a command in the execution plan, the plan should continue executing
});
Events
- 'complete'
- Fires when an entire execution plan's set of commands successfully execute.
- The following parameters will be given to the provided callback:
- stdout String - the stdout of the final command that successfully executed.
- Example usage:var ExecPlan = ExecPlan;var execPlan = ;execPlan;
- 'execerror'
- Fires whenever a command in an execution plan has an error while the plan is being executed.
- The following parameters will be given to the provided callback:
- error Error - the js Error object of the command that caused the problem.
- stderr String - the stderr of the command that caused the problem.
- Example usage:var ExecPlan = ExecPlan;var execPlan = ;execPlan;
- NOTE: Unfortunately, due to conflicts with the internals of node.js, this event cannot be named 'error'.
- 'finish'
- Fires after the conclusion of the execution of an execution plan, irrespective of whether an error occurred.
- The provided callback should expect no parameters.
- Example usage:var ExecPlan = ExecPlan;var execPlan = ;execPlan;
Public Actions
- add - adds a 'step' command to the execution plan.
- The following parameters are expected:
- [preLogic] Function - a function to call before the command is executed, but after previous
command finished.
- The preLogic function should expect the following parameters:
- stdout String - the stdout of the previously-executed step.
- The preLogic function should expect the following parameters:
- command String - command to be executed.
- [options] Object - child_process.exec options. See: child_process.exec API.
- [errorHandler] Function - a function to call if the command produces an error.
- The errorHandler function should expect the following parameters:
- error Error - js Error object that occurred during command execution.
- stderr String - the stderr of the command.
- The errorHandler function should return
false
if 'execerror' event should not be fired in addition to this errorHandler.
- The errorHandler function should expect the following parameters:
- [preLogic] Function - a function to call before the command is executed, but after previous
command finished.
- The following parameters are expected:
- continuesOnError - states whether the general policy of the exec plan is to continue when errors occur.
- return Boolean
- execute - executes all added commands in the order in which they were added.
- This order will be enforced, such that each command will not execute until previous commands finish.
- willAutoPrintErr - states whether stderr will be automatically printed to when errors occur.
- return Boolean
- willAutoPrintOut - states whether stdout will be automatically printed to after a command executes.
- return Boolean