acho

acho

An extremely simple (but powerful) logging system for NodeJS and browser.

Why

• Very easy to use, customize and extend.
• Expressive API with chaineable methods.
• Mininum dependencies, just focussing on one thing.
• Compatible with AMD/CommonJS or just global object in the browser.

Install

npm install acho

If you want to use it in the browser (powered by Browserify):

bower install acho --save

and later add it to your HTML:

<script src="bower_components/acho/dist/acho.js"></script>

Usage

First steps

Acho exports itself according to UMD best practices, which means that no matter where you are using the library, you get a version tailored for your environment.

If you're using a module loader (or Node), simple require the library as you would any other module.

If you're using a browser, the library falls back to attaching itself to window as the global Acho.

CommonJS

var Acho = require('acho');
var acho = new Acho();

Global/Browser

var acho = new Acho();

AMD

I don't use personally use AMD, so I can't conjure an example, but it should work fine as well.

It's time to use it!

acho.info('hello world');
// => 'hello world'

All public methods are chainable:

acho
.info('hello world')
.error('something bad happens');
// => 'info: hello world'
// => 'error: 'something bard happens'

Maybe you don't want to output the message, but store it for later use:

acho.push('success', 'good job!');
console.log(acho.messages.success);
// => ['good job']

If you want to print previously stored messages, just call the method print:

acho.print()
// => 'success: good job!'

You might be thinking: Can I combine both, to store and both print a message? Absolutely!

acho.add('info', 'this message is printed and stored');
// => 'info: 'this message is printed and stored'
console.log(acho.messages.info)
// => ['this message is printed and stored']

Defining the level

Establishing the loglevel is a good way to filter out undesired information from output. The available levels by default are:

• error: Display calls to .error() messages.
• warn: Display calls from .error(), .warn() messages.
• success: Display calls from .error(), .warn(), success() messages.
• info: Display calls from .error(), .warn(), success(), info() messages.
• verbose: Display calls from .error(), .warn(), success(), info(), verbose() messages.
• debug: Display calls from .error(), .warn(), success(), info(), verbose(), debug() messages.
• silly: Display calls from .error(), .warn(), success(), info(), verbose(), debug(), silly() messages.

Additionally exists two special levels:

• silent: Avoid all output.
• all: Allow print all message types.

The default log level is all. You can define it in the constructor:

var acho = new Acho({level: 'silly'})

or at runtime:

acho.level = 'debug';

Customization

You can completely customize the library to your requirements: changes colors, add more types, sort the priorities... the internal structure of the object is public and you can edit it dynamically. You have the power.

By default the messages structure is brief: Just the message type followed by the message itself.

But you can easily modify the output. For example, let's add a timestamp to each message:

acho = new Acho({
  color: true,
  level: 'silly',

  // Customize how to print the 'type' of each message
  outputType: function(type) {
    return '[' + type + '] »';
  },

  // Customize how to print the message.
  // Add things before and/or after.
  outputMessage: function(message) {
    return Date() + ' :: ' + message;
  }
});

This results in your awesome output:

acho.info('I am hungry');
// => '[ info ] » Fri Mar 13 2015 18:12:48 GMT+0100 (CET) :: I am hungry'

If you need customize more the output you can setup .print .generateMessage (see below) that are a more low level methods for generate and print the output message.

API

.constructor({Object} [options])

Create a new logger. Available options:

• color {Boolean}: Enable or disable colorized output. false by default.
• level {String}: Provides the logging level. all by default.
• types {Object}: You can provide the types and priorities.
• print {Function}: Provides a function that determines how to print the messages. By default uses .generateMessage for generate the mesage that will be outputted.
• outputType {Function}: Provides a function to customize the type in the output.
• outputMessage {Function}: Provides a function to customize the message in the output.
• generateMessage {Function}: Provides a function that generate the message to be outputted. It combines other internal methods for generate the output (as .isPrintable or .colorize) and normally you are not interested in the definition of it, but you can provide it as option as well.

.push({String} <type>, {String} <message>)

Store a message of given type internally.

.add({String} <type>, {String} <message>)

Store a message of given type internally and also output it.

For each level you have a function following the pattern:

.[loglevel]({String} <message>)

For each log level that you declared in the constructor (or the default log levels provides by the library if you don't declare nothing) will be created a function with the same name to output a message with these log level.

.isPrintable({String} <type>)

Determines if a type of message should be outputted.

.colorize({String} <color> {String} <message>)

Determines is a instance of acho is outputted with colors.

License

MIT © Kiko Beats

Changelog

2.0.0 (2015-07-31)

• 2.0.0 releases (0daf159)
• avoid avoid colorize messages in production under NodeJS (f6d2d54)
• colors by default (103194b)
• documentation refactor (bc43872)
• expose generateMessage (57c3b9f)
• little refactor. (4046677)
• Update README.md (fd0acee)
• updated (2bec971)
• updated bumped settings (3025456)

<a name="1.0.8"></a>