Go Logs

A configurable logger with message filtering, formatting and handling.

• version: 1.0.1
• license: GNU LGPLv3

Installation

npm i go-logs

or

yarn add go-logs

To load using a script tag in a browser, specify the build file in the dist folder. The module is assigned to a global variable "Logs".

<script src="dist/go-logs.min.js"></script>

Usage

ES6

Default Logger

import { Logger, Level } from 'go-logs'

Logger.getDefault().setLevel(Level.INFO);

Logger.debug("hi");    // => not logged.
Logger.info("hello");  // => prints "hello" to the console.

Or

import { info, debug } from 'go-logs'

debug("hi");    // => prints "hi" to the console.
info("hello");  // => prints "hello" to the console.

Custom Logger

import { Logger, Level } from 'go-logs'

const logger = new Logger();

// only allow string messages
logger.addFilter((level, msg) => {
	return typeof msg === "string";
})

// print the message to the console.
logger.addHandler((level, msg) => {
	console.log(msg);
});

logger.setLevel(Level.INFO);

logger.debug("hi");     // => not logged.
logger.info(1)          // => not logged.
logger.info("hello");   // => prints "hello" to the console.

Documentation

Table of Contents

• Logger
  • Parameters
  • getDefault
  • getName
  • setName
  • getLevel
  • setLevel
  • getAllFilters
  • addFilter
  • removeFilter
  • clearFilters
  • getAllHandlers
  • addHandler
  • removeHandler
  • clearHandlers
  • getFormatter
  • setFormatter
  • log
  • trace
  • debug
  • info
  • warn
  • error
  • fatal
• getName
• setName
  • Parameters
• getLevel
• setLevel
  • Parameters
  • Examples
• getAllFilters
• addFilter
  • Parameters
  • Examples
• removeFilter
  • Parameters
• clearFilters
• getAllHandlers
• addHandler
  • Parameters
  • Examples
• removeHandler
  • Parameters
• clearHandlers
• getFormatter
• setFormatter
  • Parameters
  • Examples
• log
  • Parameters
• trace
  • Parameters
  • Examples
• debug
  • Parameters
• info
  • Parameters
• warn
  • Parameters
• error
  • Parameters
• fatal
  • Parameters
• messageCallback
  • Parameters
• Level
  • get
    • Parameters
  • below
    • Parameters
  • above
    • Parameters

Logger

A Logger object is used to log messages. A log level can be specified to allow only messages that is equal to or above the minimum severity level and additionally filters can be added to further narrow down to specific messages. Messages that meet the level requirement and pass the filters will be forwarded to registered handlers to be processed. Additionally a formatter can be added to format a message before forwarding it to the handlers.

When the constructor is used:

• With no argument, it creates a new instance with default constructor options.
• With a plain object argument, it creates a new instance with the specified constructor options.
• With a Logger instance, it creates a copy of the instance.
• As a function, Logger(value) converts the argument to a Logger instance. If the value is already a Logger, it returns the instance.

Log levels

• OFF: 0 ("off")
• ALL: 1 ("all")
• TRACE: 100 ("trace")
• DEBUG: 200 ("debug")
• INFO: 300 ("info")
• WARN: 400 ("warn")
• ERROR: 500 ("error")
• FATAL: 600 ("fatal")

Parameters

• arg (Object | Logger)? constructor options or an instance of logger to copy.

  • arg.name string? The name of the Logger.
  • arg.level (Level | number | string)? The minimum severity level to log.
  • arg.filters Array<Function>? Message filters.
  • arg.handlers Array<Function>? Message handlers.
  • arg.formatter Function? Message formatter.

Meta

• version: 1.0.0
• author: Michael Ko ([e-mail])

getDefault

The default Logger instance.

Meta

• since: 1.0.0

getName

Calls the getName method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

setName

Calls the setName method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

getLevel

Calls the getLevel method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

setLevel

Calls the setLevel method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

getAllFilters

Calls the getAllFilters method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

addFilter

Calls the addFilter method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

removeFilter

Calls the removeFilter method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

clearFilters

Calls the clearFilters method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

getAllHandlers

Calls the getAllHandlers method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

addHandler

Calls the addHandler method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

removeHandler

Calls the removeHandler method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

clearHandlers

Calls the clearHandlers method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

getFormatter

Calls the getFormatter method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

setFormatter

Calls the setFormatter method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

log

Calls the log method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

trace

Calls the trace method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

debug

Calls the debug method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

info

Calls the info method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

warn

Calls the warn method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

error

Calls the error method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

fatal

Calls the fatal method on the default Logger instance with the provided arguments and returns the result.

Meta

• since: 1.0.0

getName

Returns the name of this Logger.

Returns string The name of this Logger.

Meta

• since: 1.0.0

setName

Sets the name of this Logger.

Parameters

• name string The new name.

Returns Logger This Logger instance.

Meta

• since: 1.0.0

getLevel

Returns the log level specified for this Logger.

Returns Level The log level.

Meta

• since: 1.0.0

setLevel

Sets the minimum severity level that is allowed to be logged by this Logger. Only messages with a severity level equal to or higher than the specified level will be logged and if the log level is set to Level.OFF, no messages will be logged.

Parameters

• level Level The log level.

Examples

// log all messages
logger.setLevel(Level.ALL);

// log only messages with a severity level equal to Level.INFO or higher. 
logger.setLevel(Level.INFO);

// turn off logging
logger.setLevel(Level.OFF);

Returns Logger This Logger instance.

Meta

• since: 1.0.0

getAllFilters

Returns all of the message filters attached to this Logger.

Returns Array<Function> The filter functions in a new array.

Meta

• since: 1.0.0

addFilter

Adds a message filter which tests if a message should be forwarded to the handlers. A truthy value must be returned from all the filters attached in order for the message to be forwarded to the handlers for processing.

Parameters

• filter messageCallback The filter function to add.

Examples

// add a filter that only accepts string messages.
logger.addFilter((level, msg) => {
     return typeof msg === "string";
});

logger.info("hi"); // => logged
logger.info(1);    // => not logged

Returns Logger This Logger instance.

Meta

• since: 1.0.0

removeFilter

Removes a message filter from this Logger.

Parameters

• filter Function The filter function to remove.

Returns Logger This Logger instance.

Meta

• since: 1.0.0

clearFilters

Removes all message filters from this Logger.

Returns Logger This Logger instance.

Meta

• since: 1.0.0

getAllHandlers

Returns all of the log handlers attached to this Logger.

Returns Array<Function> The handler functions in a new array.

Meta

• since: 1.0.0

addHandler

Adds a message handler which will process messages that meet both the minimum severity level and filters.

Parameters

• handler messageCallback The handler function to add.

Examples

// log messages to the console.
logger.addHandler((level, msg) => {
     console.log(level.name, msg);
});

Returns Logger This Logger instance.

Meta

• since: 1.0.0

removeHandler

Removes a message handler from this Logger.

Parameters

• handler Function The handler function to remove.

Returns Logger This Logger instance.

Meta

• since: 1.0.0

clearHandlers

Removes all message handlers from this Logger.

Returns Logger This Logger instance.

Meta

• since: 1.0.0

getFormatter

Returns the current message formatter.

Returns Function The formatter function if specified; null otherwise.

Meta

• since: 1.0.0

setFormatter

Sets a message formatter to format accepted messages before forwarding to the handlers.

Parameters

• formatter messageCallback The formatter function to use to format messages.

Examples

// prefix the level name.
logger.setFormatter((level, msg) => {
     return level.name + ":" + msg;
});

logger.info("hello"); // => logs "info:hello"

Returns Logger This Logger instance.

Meta

• since: 1.0.0

log

Logs a message with the specified level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers.

Parameters

• level (number | string | Level) The message level.
• msg ...any The message parameters.

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

trace

Logs a message with the Level.TRACE level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers. This is same as calling log(Level.TRACE, msg)

Parameters

• msg ...any The message parameters.

Examples

trace("data");

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

debug

Logs a message with the Level.DEBUG level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers. This is same as calling log(Level.DEBUG, msg)

Parameters

• msg ...any The message parameters.

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

info

Logs a message with the Level.INFO level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers. This is same as calling log(Level.INFO, msg)

Parameters

• msg ...any The message parameters.

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

warn

Logs a message with the Level.WARN level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers. This is same as calling log(Level.WARN, msg)

Parameters

• msg ...any The message parameters.

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

error

Logs a message with the Level.ERROR level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers. This is same as calling log(Level.ERROR, msg)

Parameters

• msg ...any The message parameters.

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

fatal

Logs a message with the Level.FATAL level and the message parameters. If the message meets the minimum log level and filter requirements, it will be forwarded to the handlers. Additionally, if a formatter is set, the message will be formatted before being passed to the handlers. This is same as calling log(Level.FATAL, msg)

Parameters

• msg ...any The message parameters.

Returns boolean true if the message is logged, false otherwise.

Meta

• since: 1.0.0

messageCallback

Type: Function

Parameters

• level Level The severity level of the message.
• msg ...any The message parameters.

Level

The Level class defines the standard logging levels that can be used to control logging output.

• OFF: 0 ("off")
• ALL: 1 ("all")
• TRACE: 100 ("trace")
• DEBUG: 200 ("debug")
• INFO: 300 ("info")
• WARN: 400 ("warn")
• ERROR: 500 ("error")
• FATAL: 600 ("fatal")

Meta

• since: 1.0.0

get

Returns a Level object by the name or value. If no match is found in the Level.values, undefined is returned.

Parameters

• nameOrValue (string | number) The name or the value of the Level object to get.

Returns Level The Level object that has the name or the value if found; undefined otherwise.

Meta

• since: 1.0.0

below

Returns a Level object that is one level below the specified level. If no match is found in the Level.values, undefined is returned.

Parameters

• nameOrValue (string | number | Level) The name or value of the level to find the one level below.

Returns (Level | undefined) The Level object that is one level below the specified level if found; undefined otherwise.

Meta

• since: 1.0.0

above

Returns a Level object that is one level above the specified level. If no match is found in the Level.values, undefined is returned.

Parameters

• nameOrValue (string | number | Level) The name or value of the level to find the one level above.

Returns (Level | undefined) The Level object that is one level above the specified level if found; undefined otherwise.

Meta

• since: 1.0.0