firewood v0.0.0

Firewood

Very simple log class with support for filtering, sprintf style input, custom formatting, and custom message handling.

This utility is meant to provide the bare minimum of functionality that a logger should have. More functionality can be added by using a custom formatter or handler.

If you publish a Firewood formatter or handler module, please add the firewood tag to the package.

Features:

• Instances
• Standard Levels Trace Debug Info Warn * Error
• Custom Formatting
• Custom Output
• Mini-Templating (e.g. sprintf, console.log)

Installation

npm install firewood --save

API

Class: Firewood

All methods return a reference to the Firewood instance for chaining.

new Firewood(options)

Firewood.create(options)

options is an object with the following defaults, unless Firewood.defaults has been modified:

{
	level: Firewood.ERROR,
	formatter: Firewood.defaultFormatter,
	handler: Firewood.defaultHandler
}

firewood.trace(format[, arg1[, arg2, ...]])

firewood.debug(format[, arg1[, arg2, ...]])

firewood.info(format[, arg1[, arg2, ...]])

firewood.warn(format[, arg1[, arg2, ...]])

firewood.error(format[, arg1[, arg2, ...]])

Add a log message with a log level corresponding to the method name.

The format and additional arguments are passed to the sprintf-js module's vsprintf() function for compilation into a single string, before the string is passed to the Firewood formatter and handler. This mimics the behavior of console.log().

firewood.setLevel(level)

level can be a number, string, or constant.

Valid string/number/constant values:

• 'trace' = 0 = Firewood.TRACE
• 'debug' = 1 = Firewood.DEBUG
• 'info' = 2 = Firewood.INFO
• 'warn' = 3 = Firewood.WARN
• 'error' = 4 = Firewood.ERROR
• 'none' = 5 = Firewood.NONE

firewood.setFormatter(formatter)

formatter can be a function, an object with a format() method, or false/null.

If formatter is a function/object, the function will be passed the text of the log message, a numeric log level, and the time of the message as a Date instance. It should return the final log message text, or null to filter out the message completely. If null is returned the message will not be passed to the message handler.

if formatter is false or null, then messages will be passed to the handler without formatting.

Example (default formatter):

firewood.setFormatter(function(text, level, date) {
	return sprintf('[%s] %s - %s', getLevelName(level).toUpperCase(), date.toISOString(), text);
});

firewood.setHandler(handler)

handler can be a function, an object with a handle() method, a writable stream, or another Firewood instance.

The function receives the same parameters as the formatter, however it should not modify the text value of the message. Instead it should record or output the message.

Example (default handler):

firewood.setHandler(function(text, level, date) {
	switch (level) {
		case Firewood.TRACE:
			console.log(colors.gray(text));
			break;
		case Firewood.DEBUG:
			console.log(text);
			break;
		case Firewood.INFO:
			console.info(colors.cyan(text));
			break;
		case Firewood.WARN:
			console.warn(colors.yellow(text));
			break;
		case Firewood.ERROR:
			console.error(colors.red(text));
			break;
		default:
			console.log(text);
			break;
	}
});

Example (writing directly to stdout):

firewood.setHandler(process.stdout);

firewood.writable(level)

level an optional log level or function which accepts a log message and returns a log level. If a level function returns null, then the log message is discarded.

options is an options object with the following default value:

{
	keepEOL: false
}

By default, the writable steam will trim a single trailing EOL from each message. The handler is expected to add it's own trailing EOL if necessary. Setting the "keepEOL" option to true will leave the last EOL alone.

Returns a writable stream that will log all messages written to it.

firewood.close()

All log messages will be silently ignored after this method is called.

Firewood.TRACE

Firewood.DEBUG

Firewood.INFO

Firewood.WARN

Firewood.ERROR

Firewood.NONE

Log level constants used with the setLevel() method.

Firewood.getLevelName(level)

level can be the log level name or number.

Returns The lower case string name of the log level. If the level is not a valid log level number or name, then an empty string will be returned.

Firewood.getLevelNumber(level)

level can be a log level name or number.

Returns the number value of the log level. If the level is not a valid level number or name, then NaN will be returned;

Firewood.defaultFormatter(text, level, date)

The default formatter which prepends all messages with the upper case level in square brackets [], followed by the ISO-8601 timestamp, a hyphen, and then the text of the log message.

Example:

[DEBUG] 2015-01-23T12:34:56.789Z - message

Firewood.defaultHandler(text, level, date)

The default handler function which prints all log messages to the console. Trace and debug levels are output using the console.log() method. All other levels are output using the corresponding console method. It also color codes the messages using the colors module.

Level/Color:

• trace = gray
• debug = cyan
• info = normal
• warn = yellow
• error = red

Firewood.defaults

The default options object for all new Firewood instances. This property can be modified to change the default options for all future Firewood instances.

Initially property has the following default value:

{
	level: Firewood.DEBUG,
	formatter: Firewood.defaultFormatter,
	handler: Firewood.defaultHandler
}