firewood

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 or an object with a format() method.

The function will be passed a numeric log level as the first argument, and the text of the log message as the second argument. The function 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.

Example (default formatter):

function(level, text) {
	return '[' + Firewood.getLevelName(level).toUpperCase() + '] ' + text;
}

firewood.setHandler(handler)

handler can be a function or an object with a handle() method.

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):

function(level, text) {
	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;
	}
}

Firewood.TRACE

Firewood.DEBUG

Firewood.INFO

Firewood.WARN

Firewood.ERROR

Firewood.NONE

Log level constants used with the setLevel() method.

Firewood.getLevelName(level)

level should be the numeric value of a log level. The lower case string name of the given numeric level will be returned. If level is not a number or it's out of range, then level will be converted to a string and returned.

Firewood.defaultFormatter(level, text)

The default formatter which prepends all messages with the upper case level in square brackets [].

Firewood.defaultHandler(level, text)

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 = normal
• info = cyan
• 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
}