observatory

Observatory

Beautiful UI for showing tasks running on the command line.

Purpose

Instead of just logging long running tasks to the console, give your users a simple status dashboard.

Installation

$ npm -g install observatory

Examples

node ./examples/buzzwords.js

An example using fake data that tries to look like a real-world usage.

node ./examples/long-line.js

An example of what happens when text is so long it needs to wrap to another line.

Usage Example

var observatory = require('observatory');

//add a task to display
var task = observatory.add('Install packages...');

//while working on the task, update the status
task.running('Copying Files');

//optionally give details
task.details(percent + '% ' + filename);

//chain commands
task.status('Compressing Images')
    .details(directoryName);

//when complete
task.done('Finished!');

//or if it failed
task.fail('Ooops');

Terminology

[Test Runner] Running tests on Safari  Running Now  50%  CSS3 Tests
⇧ prefix      ⇧ description            ⇧ status     ⇧ details

API

observatory.add(description)

description string Required description.
returns a new task

Adds a task to the console. This method returns a task object, you should store it in a variable so you can use it for the methods bellow.

var copyFilesTask = observatory.add('Copy files');

Task Methods

All task methods return the task object so that you can chain functions, such as task.done().status('Installed!');.

task.status(statusLabel)

statusLabel string Set the status value.

Displays a short message to the right of the description. Use it to show users in a word or two that suggests what is happening.

Examples:

• task.status('Downloading');
• task.status('Running');
• task.status('Complete');

task.details(detailsLabel)

detailsLabel string Set the details value.

Optional provide details about what's happening, such as file names, urls, tests names.

Examples:

• task.details('Copying var/tmp/whatever to var/whater/tmp');
• task.details('Compressing bigimage.png');
• task.details('Testing services');

task.done(statusLabel)

statusLabel string Set the status value. Default: ✓ Done.

• task.done();
• task.done('Compressed!')

task.fail(statusLabel)

statusLabel string Set the status value. Default: ✗ Failed.

• task.fail();
• `task.fail('Disconnected');

Override Settings

observatory.settings(settingsObject)

Tweak how tasks are rendered.

settingsObject

• width Integer, width in characters of the description and status area. This is used to right justify the status. Default is 55.
• prefix Sting, Text to prepend each line. Default is ' ⫸ '.
• formatStatus Function(statusLabel, STATE)

returns observatory so you can use it on the require statement.

var observatory = require('observatory').settings({
  prefix: '[bower] '.white
});

observatory.STATE

A constant for the different states. Only useful if you need to change formatStatus above.

The values:

• observatory.STATE.active Defaults to using default console color.
• observatory.STATE.done Defaults to using green.
• observatory.STATE.fail Defaults to using red.

Acknowledgements

Inspiration

• My coworker Nick at Opower for inspiring the need for this library.
• Bower, inspiring the clean layout.
• Inqurire.js, for showing console apps can have a nice UI.
• Grunt, for making it easy and fun to build the kind of tasks that could benefit from this.

Dependencies

• cli-color, used for coloring text and moving the cursor. It does not modify the string prototype and supports moving the cursor around. Feel free to use any coloring library to color the text.

Release History

• 15 October 2013 - 0.0.1 - First version

License

Copyright (c) 2013 Dylan Greene
Licensed under the MIT license.