woad

Yet another Node.js logger.

Installation

Install from GitHub by downloading the zip file and 'extract all' into a folder.

Alternatively clone straight from github using command:

git clone https://github.com/kelvin-martin/woad.git

This will install all the source files from github and setup a local git repository.

Usage

Note: the module must be installed before use.

const lg = require('woad.js');

lg.create({'file': 'logger.txt'});

lg.info('Hello World.');

API

To use the logger in your code include the woad module with:

const lg = require('woad.js');

woads's level definitions loosely follow the npm error levels.

ERROR = 0;
WARN = 1;
INFO = 2;
VERBOSE = 3;
DEBUG = 4;
TRACE = 5;

Functions

create(options)

This creates a sink that the logger uses to record messages. The object passed into create() contains all the configuration options for that sink. See 'Configuration object' below for a description of the options. create() returns a string representing the name of the sink registered or null if the name already exists. The returned name can be used in calls to delete(), setlevel(), stop() and resume().

delete(name)

Deletes a registered sink from the logger. name is the string returned from create().

setlevel(name, level)

Sets the logging level for the named sink. name is the string returned from create(). level is one of woads level definitions.

stop(name)

Stops logging on the named sink. If no name passed then all logging is stopped. name is the string returned from create().

resume(name)

Resumes logging on the named sink. If no name passed then all logging is stopped. name is the string returned from create().

log(level, message)

Logs a message to all registered sinks if the message level is less than or equal to the currently set sink level. message is a string or node buffer. level is one of woads level definitions.

error(message)
warn(message)
info(message)
verbose(message)
debug(message)
trace(message)

The above are helper functions which can be used as an alternative to log() without passing in the level for the message. message is a string or node buffer.

Configuration object

The configuration options for a sink can be defined by following options object:

// default configuration options
const default_options = {
	'name': 'default-log',
	'file': 'log.txt',
	'encoding': 'utf8',
	'msg_length': 60,
	'format': 'DL',
	'level': module.exports.INFO,
	'log_state': true,
	'callback': default_handler
};

A configuration object which contains zero or more of the specified fields is required to register a sink with a call to create(). If an empty object is passed then all default settings are used. If any of the fields are omitted then the default settings for that field are used.

'name'         Name (string) used to denote the configured sink. This
               name is returned by create(). The name string is always
               changed to its lowercase equivalent. If name is 
               'console' (case-insensitive) then the file option is 
               ignored and all logging is output to Node's console.
'file'         Path (string) of the file that is used for the sink.
'encoding'     The encoding (string) used for saving the message to the
               sink. Valid encodings are Node's encoder string.
               e.g. 'ascii', 'utf8', 'hex'  etc.
'msg_length'   The length (number) of the message recorded. Messages
               longer than 'msg_length' are truncated. The date, time
               and level are not taken into account only the message.
'format'       A format (string) that specifies what information is
               recorded along wth the message. The complete format
               string is 'DTL' which means 'D=date T=time L=level'.
'level'        The level (number) to use to filter messages recorded to
               that sink. level is one of woads level definitions.
               The level for the sink can be changed using setlevel()
'log_state'    The state (boolean) of the logging for that sink. 
               This state can be set to on (true) or off (false) using
               stop() or resume().
'callback'     A callback (function) which is called when a message is
               written to the sink. The callback will take a standard
               node error object which will be null if successful or
               error details if an error occured during the write.

License

woad is freely distributable under the terms of the MIT license.