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) >.<
$ npm install exec-plan
/**
* 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"
}
}
$ npm install
/**
* An example of the most basic usage.
*/
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new ExecPlan();
execPlan.add('ls -la');
execPlan.add('grep "test" ./*');
execPlan.add('ps -ef');
execPlan.execute();
/**
* An example with more fine-grained control.
*/
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new ExecPlan();
// attach event handlers to the events exposed by ExecPlan
execPlan.on('execerror', function (error, stderr) {
console.log('an error happened in one of the steps in execution plan');
console.log(error); // the error object for the process that caused the problem
console.log('the stderr for the process that caused the problem is ' + stderr);
});
execPlan.on('complete', function (stdout) {
console.log('the entire execution plan finished, i.e., all child processes completed with no errors');
console.log('the stdout for the final step in the execution plan is ' + stdout);
});
// first, setup a vanilla set of commands
execPlan.add('ls -la');
execPlan.add('ps -ef');
// 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.add(function (stdout) {
process.chdir('/tmp'); // run this logic before the command is executed
}, 'grep "test" ./*');
// now, add a command that will include an error handler that will run before the 'error' event is fired.
execPlan.add('some_command_that_does_not_exist', function (error, stderr) {
console.log('ERROR: ' + stderr);
console.log(error); // a standard js Error object
return false; // return false to signal to execPlan that the 'error' event should not be fired
});
// run the set of commands
execPlan.execute();
/**
* An example showing error-handling
*/
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new 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.on('finish', function () {
console.log('The execution plan has finished executing. An error may or may not have occurred.');
});
execPlan.add('./command_that_does_not_exist', function (error, stderr) {
console.log('an error occurred with stderr: ', stderr);
// nothing is returned by this command, so the 'continueOnError' policy will be followed, and the
// the 'execerror' event will be fired
});
execPlan.add('./another_command_that_does_not_exist', function (error, stderr) {
// return true to signal that the plan should continue executing irrespective of 'continueOnError' policy;
// also, a return of true or false signals that the 'execerror' event should not fire.
return true;
});
execPlan.add('./yet_another_command_that_does_not_exist', function (error, stderr) {
// return false to signal that the plan should stop executing irrespective of 'continueOnError' policy;
// again, returning false signals that the 'execerror' event shoudl not fire.
return false;
});
execPlan.execute();
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
});
'complete'
Example usage:
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new ExecPlan();
execPlan.on('complete', function (stdout) {
// provide code to do processing after all commands have successfully been executed.
});
'execerror'
Example usage:
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new ExecPlan();
execPlan.on('execerror', function (error, stderr) {
// provide code to handle any command errors.
});
'finish'
Example usage:
var ExecPlan = require('exec-plan').ExecPlan;
var execPlan = new ExecPlan();
execPlan.on('finish', function () {
// provide any code that should be called whenever an execution plan stops executing.
});
true
or false
if 'execerror' event should not be fired in
addition to this errorHandler.true
, then the execution plan will continue executing, irrespective of "continueOnError" policy.false
, then the execution plan will stop executing, irrespective of "continueOnError" policy.