cllc

cllc

Command Line Logger and Counter for console.

Features

• nice colored log messages with configurable timestamps, tags and log level labels.
• console indicator with easy incrementable counters
• logger and counter works together without erasing or rewriting each other.
• automatic 'file mode' (no colors, no counters) if output piped to file or other shell stream.

Why?

Because some scripts works for a long time and need pretty good console indicators for monitoring how they are. But some of them are too easy for blessed-contrib or even for winston. For example, long queues of http requests or database queries. I developed this module for scraping scripts, but it can be used a lot wherever else.

Contributing

No any specific rules for now. Just open issue or create PR if you want.

Install

npm install cllc

Usage

Logger

const log = require('cllc')();

// //or//
// const log = require('cllc')('TAG', '%F %T');
// default tag and date format (see below)

log('Sample message');

Log messages

It's important, that log message is not required. cllc can output string with only timestamp/label/tag (if not empty). If any params sent to log then log message will be created same way as in util.format.

log('This is a log message string', 'This is another log message string');
log(); //log string without message
log({a: 1}, [1, 2], new Date(), null); // same way as in `util.format`

Log level labels

Default log level label is empty (nothing printed) but you can set default label or specify it explicitly for every log string.

log('log string with empty log level label (default)');
log.trace('log string with label <TRACE>'); //short form is log.t
log.debug('log string with label <DEBUG>'); //short form is log.d
log.info('log string with label <INFO>');   //short form is log.i
log.warn('log string with label <WARN>');   //short form is log.w
log.error('log string with label <ERROR>'); //short form is log.e

log.level('trace'); //set default log level label to <TRACE>
log.level('error'); //set default log level label to <ERROR>
log.level();        //set empty default log level label

Five log levels are possible: trace, debug, info, warn and error. Any other parameter in log.level sets empty default log level label.

Timestamps

Timestamps are formatted by strftime. By default format string is '%T', but you can change it at any time. Like this:

const log = require('cllc')(null, '%F %T');
log('log string with date format "%F %T"');
log.dateFormat('%F');
log('log string with date format "%F"');
log.dateFormat();
log('log string with no date displayed');

log.dateFormat('%F %T');

Any string are correct, even if it doesn't contain any formatting symbols at all.

If you want to disable timestamps just use any falsy value. Like this:

log.dateFormat('');
// //or//
log.dateFormat();

Any parameter of log.dateFormat that is not a string or falsy will be ignored.

Logger tags

Usually tags used if you want to identify several loggers from different modules or functions. Tag is just a short string. By default tag is empty, but you can specify it any time. Like this:

const log = require('cllc')('TAG1');
log('log string with tag "TAG1"');
log.tag('Tag2');
log('log string with tag "Tag2"');
log.tag();
log('log string with no tag');

You can use module variable on cllc init or as parameter of log.tag. In that case module filename and dir will be in tag.

const log = require('cllc')(module);
log('log string with something like "my-module/index" in tag');

Pretty errors

When log level is 'error' and only argument is an instance of Error, then output will be prettified by errsome.

log.e(new Error('TEST')); // will output something like this:

// [01:01:01] <ERROR>
// { name: 'Error',
//   message: 'TEST',
//   stack:
//    [ 'at Object.<anonymous> (/Users/astur/js/github/cllc/_test.js:9:7)',
//      'at Module._compile (module.js:624:30)',
//      'at Object.Module._extensions..js (module.js:635:10)',
//      'at Module.load (module.js:545:32)',
//      'at tryModuleLoad (module.js:508:12)',
//      'at Function.Module._load (module.js:500:3)',
//      'at Function.Module.runMain (module.js:665:10)',
//      'at startup (bootstrap_node.js:187:16)',
//      'at bootstrap_node.js:607:3' ] }

Counter

Counter is a text in the end of console, contains digital value(s) that are incrementing step by step.

Start counter

log.start(); //same as log.start('%s');
// //or//
// log.start('%s tasks done.', 0);
// //or//
// log.start('%s foo, %s bar, %s baz', 0, 1, 2);

Increment counter

log.step(); // same as step(1);
// //or//
// log.step(5);
// //or//
// log.step(0, 0, 1);

Or another way:

log.inc(1); // same as step(1);
// //or//
// log.inc(3); // same as step(0, 0, 1)

Stop counter

log.stop(); // stop and clear
// //or//
// log.finish(); // stop and save counter text
// //or//
// log.finish('Well done %s tasks!', 100); // stop with special text
// //or//
// log.finish('%s foo, %s bar, %s baz', 100, 200, 300); // stop with special text

Restart/change counter

Calling log.start starting new counter with new text and new values. If another counter was active on that moment it will be destroyed silently (if you want save it - call log.finish before start next counter).

Current counter text and values are availiable via log.text and log.counters functions.

log.start('First counter [%s][%s]', 1, 5);
// do something like `log.step` here
// then:
log start(doSomething(log.text()), ...doSomethingElse(log.counters()));

Safe logger

If counter are visible - log strings appear on string above counter text and will not be erased by counter. So use log from cllc instead console.log when counter active.

log.start('[%s]');
log.step();
log('TEST');
log.finish();

// result output:
// TEST
// [1]

'file mode'

If you want pipe log to file - just do it. It is not necessary to code changes or configs. cllc can detect that script runs not in TTY and suppress colors and counters automaticly. You can test it this way:

node your-script.js | cat

License

MIT