planify

Plan a series of concrete steps and display their output in a beautiful way.

Ever wanted to write a simple CLI that run a series of tasks with beautiful output? I did and I always ended up doing a thin wrapper repeatedly. This library provides a concise way to define these tasks while offering a handful of reporters to output the progress in a variety of ways.

Installation

$ npm install planify

Usage

The API is very simple, yet very powerful:

const planify = require('planify');

planify()
.step('Synchronous step', (data) => {
    console.log('A sync step in which data is', data);
    data.foz = 'baz';  // Set some data to the next step
})
.step('Callback step', (data, done) => {
    console.log('A callback step in which data is', data);
    setTimeout(done, 500);
})
.step('Promise step', (data) => {
    console.log('A promise step in which data is', data);
    return new Promise((resolve) => {
        setTimeout(resolve, 500);
    });
})
.phase('Some group of steps', (phase) => {
    phase.step('Synchronous step inside a phase', (data) => {
        console.log('A sync step inside a phase in which data is', data);
    });
})
.run()
// Run returns a promise but callback style is also supported
.then(() => process.exit(), (err) => process.exit(1));

You can build as many nested phases as you wish. API is chainable to make it easier to build your plan.

Running this would look like this:

But changing the reporter to spec would look like this:

This is very similar to the mocha's spec reporter isn't it? In fact a lot of the API was inspired in it. Finally, changing the reporter to progress would show a beautiful progress bar instead:

As you can see, changing the appearance of the output is very easy. You may even allow your CLI users to choose the reporter by mapping --reporter to options.reporter by using yargs or something similar. Cool huh?

Reporters

The are several built-in reporters:

• blocks: blocks is the default reporter and it outputs everything, including stuff printed to the stdout and stderr.
• spec: spec reporter is very similar to mocha's spec reporter but stuff written to the stdout and stderr are hidden.
• progress: progress reporter shows a beautiful progress bar showing the overall progress of the plan; stuff written to the stdout and stderr are hidden.
• json: json reporter outputs a machine readable object with all the plan lifecycle events.
• silent: silent reporter which simply outputs nothing.
• spinner: a simple reporter which prints errors or a spinner when the process is running.

NOTE: Some reporters will auto-indent output unless when doing prompting.

You can easily make your own reporter. Take a look at the json reporter implementation for an example. You may use a custom reporter like this:

// my-reporter.js
function myReporter(options) {
    /* ... */

    return {
        plan: {
            start() { /* ... */ },
        },
    };
}

module.exports = myReporter;

// example.js
const planify = require('planify');
const myReporter = require('./my-reporter');

planify()
.step('Do something', () => { /* ... */ })
.run({
    reporter: myReporter({ /* reporter options if any */ })
});

/* ... */

One cool feature of the reporters is that they can be async. You may return promises or use callbacks to do async reporting (e.g.: save stuff to a database).

Feel free to make a PR to add your reporter to the built-in reporters.

Errors

All reporters print errors in a consistent way:

[err.code|err.name if !== 'Error'] err.message

[err.detail]

[err.stack if err.hideStack === false]

By default, the stack trace will be printed if there's no err.detail. You can override this behavior by setting err.hideStack to true or false to hide or show respectively.

Full API

planify([data])

Creates a plan where data is the object that is going to be passed to steps.

const planify = require('planify');
const plan = planify({ foo: 'bar' });

.step(label, [options], fn)

Adds a step with label, executing fn when it's time for the step to run.

The fn function will receive the plan data as the first argument which allows you to pass data to other steps. As show above, fn may return a promise or use callbacks to do asynchronous stuff.

Available options:

• fatal: False to continue executing if this step fails, defaults to true.
• mute: True to mute stdout and stderr completely during the execution of this step independently of the reporter being used , defaults to false; stdout and stderr can be muted independently by passing an object, e.g.: { stdout: true, stderr: false }.
• slow: Amount of time in ms to consider this step slow, defaults to 200.

const planify = require('planify');
const plan = planify();

plan.step('Some cool step', { fatal: false }, (data) => {
    throw new Error('This will fail but continue to the next step');
});
plan.step('Some cool step', { mute: true }, (data) => {
    console.log('This will not be logged');
});
plan.step('Some cool step', { slow: 500 }, (data, done) => {
    // Will be considered slow
    setTimeout(done, 600);
});

.phase(label, fn)

Adds a phase with label to the plan, executing fn with a phase object to define the phase plan.

The phase object has the step, phase and merge methods, allowing you to build a hierarchy of other phases and steps.

const planify = require('planify');
const plan = planify();

plan.phase('Phase 1', (phase) => {
    phase.step('Inner step', () => {});
    phase.phase('Inner phase', () => {});
});

.merge(plan)

Merges a plan into self, which may be a plan or a phase.

The child steps and phases of plan becomes children of self. Additionally, the data associated with the plan are shallow copied to self.

const planify = require('planify');

const plan1 = planify()
.phase('Phase 1', (phase) => {
    phase.step('Inner step', () => {});
    phase.phase('Inner phase', () => {});
});

const plan2 = planify()
.phase('Phase 2', (phase) => {
    phase.step('Inner step', () => {});
    phase.phase('Inner phase', () => {});
})
.merge(plan1);

.run([options])

Runs the plan. Returns a promise that will be resolved when the plan succeeds or rejected if any of the steps failed. You may pass a callback as the second argument instead.

const planify = require('planify');
const plan = planify();

plan.step('Some cool step', (data) => {
    /* ... */
});

plan.run()
.then(() => process.exit(0), () => process.exit(1));

// or you may use callback style
plan.run((err) => {
    process.exit(err ? 1 : 0);
});

Available options:

• reporter: The reporter to be used which can be a string or a reporter object, defaults to blocks.
• exit: True to exit automatically after running, defaults to false. If the plan fails with an error that has err.exitCode, the program will exit with that code.

Caveats

planify hooks into process.stdout.write and process.stderr.write to allow reporters to style or mute output done inside steps. Thought, it's impossible to do that when using child_process#spawn or child_process#exec with options.stdio set to inherit. Please avoid it and listen to data events from stdout and stderr instead:

// Example using child_process#spawn
const spawn = require('cross-spawn-async');
const planify = require('planify');

planify({ exit: true })
.step('Executing npm install', (done) => {
    const npm = spawn('npm', ['install']);  // Use cross-spawn to make this work on Windows

    npm.stdout.on('data', (buffer) => process.stdout.write(buffer));
    npm.stderr.on('data', (buffer) => process.stderr.write(buffer));

    npm.on('error', done);
    npm.on('exit', (code) => {
        done(code ? new Error('npm exited with code ' + code) : null);
    });
})
.run();

// Example using child_process#exec
const cp = require('child_process');
const planify = require('planify');

planify({ exit: true })
.step('Executing npm install', (done) => {
    // Note that output is buffered :(
    cp.exec('npm install', (err, stdout, stderr) => {
        stdout && process.stdout.write(stdout);
        stderr && process.stderr.write(stderr);
        done(err);
    });
})
.run();

Tests

$ npm test
$ npm test-cov to get coverage report

License

Released under the MIT License.