go-logs
Version:
A configurable logger with message filtering, formatting and handling.
815 lines (504 loc) • 22.6 kB
Markdown
# Go Logs
**A configurable logger with message filtering, formatting and handling.**
[](https://github.com/koyote130708/go-logs#documentation)
[](https://www.paypal.com/donate/?business=T7Q29NNMZVW98\&no_recurring=0\&item_name=Your+support+will+help+us++continue+our+work+and+improve+the+quality+of+our+products.+Thank+you!\¤cy_code=USD)
* **version**: 1.0.1
* **license**: GNU LGPLv3
<br />
## Installation
```javascript
npm i go-logs
```
or
```javascript
yarn add go-logs
```
<br />
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".
```javascript
<script src="dist/go-logs.min.js"></script>
```
<br />
## Usage
### ES6
#### Default Logger
```javascript
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
```javascript
import { info, debug } from 'go-logs'
debug("hi"); // => prints "hi" to the console.
info("hello"); // => prints "hello" to the console.
```
#### Custom Logger
```javascript
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.
```
<br />
## Documentation
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
#### Table of Contents
* [Logger](#logger)
* [Parameters](#parameters)
* [getDefault](#getdefault)
* [getName](#getname)
* [setName](#setname)
* [getLevel](#getlevel)
* [setLevel](#setlevel)
* [getAllFilters](#getallfilters)
* [addFilter](#addfilter)
* [removeFilter](#removefilter)
* [clearFilters](#clearfilters)
* [getAllHandlers](#getallhandlers)
* [addHandler](#addhandler)
* [removeHandler](#removehandler)
* [clearHandlers](#clearhandlers)
* [getFormatter](#getformatter)
* [setFormatter](#setformatter)
* [log](#log)
* [trace](#trace)
* [debug](#debug)
* [info](#info)
* [warn](#warn)
* [error](#error)
* [fatal](#fatal)
* [getName](#getname-1)
* [setName](#setname-1)
* [Parameters](#parameters-1)
* [getLevel](#getlevel-1)
* [setLevel](#setlevel-1)
* [Parameters](#parameters-2)
* [Examples](#examples)
* [getAllFilters](#getallfilters-1)
* [addFilter](#addfilter-1)
* [Parameters](#parameters-3)
* [Examples](#examples-1)
* [removeFilter](#removefilter-1)
* [Parameters](#parameters-4)
* [clearFilters](#clearfilters-1)
* [getAllHandlers](#getallhandlers-1)
* [addHandler](#addhandler-1)
* [Parameters](#parameters-5)
* [Examples](#examples-2)
* [removeHandler](#removehandler-1)
* [Parameters](#parameters-6)
* [clearHandlers](#clearhandlers-1)
* [getFormatter](#getformatter-1)
* [setFormatter](#setformatter-1)
* [Parameters](#parameters-7)
* [Examples](#examples-3)
* [log](#log-1)
* [Parameters](#parameters-8)
* [trace](#trace-1)
* [Parameters](#parameters-9)
* [Examples](#examples-4)
* [debug](#debug-1)
* [Parameters](#parameters-10)
* [info](#info-1)
* [Parameters](#parameters-11)
* [warn](#warn-1)
* [Parameters](#parameters-12)
* [error](#error-1)
* [Parameters](#parameters-13)
* [fatal](#fatal-1)
* [Parameters](#parameters-14)
* [messageCallback](#messagecallback)
* [Parameters](#parameters-15)
* [Level](#level)
* [get](#get)
* [Parameters](#parameters-16)
* [below](#below)
* [Parameters](#parameters-17)
* [above](#above)
* [Parameters](#parameters-18)
### Logger
A <code>Logger</code> 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | [Logger](#logger))?** constructor options or an instance of logger to copy.
* `arg.name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** The name of the Logger.
* `arg.level` **(Level | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))?** The minimum severity level to log.
* `arg.filters` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)>?** Message filters.
* `arg.handlers` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)>?** Message handlers.
* `arg.formatter` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?** Message formatter.
**Meta**
* **version**: 1.0.0
* **author**: Michael Ko (koyote130708@gmail.com)
#### getDefault
The default Logger instance.
**Meta**
* **since**: 1.0.0
#### getName
Calls the <code>getName</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### setName
Calls the <code>setName</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### getLevel
Calls the <code>getLevel</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### setLevel
Calls the <code>setLevel</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### getAllFilters
Calls the <code>getAllFilters</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### addFilter
Calls the <code>addFilter</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### removeFilter
Calls the <code>removeFilter</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### clearFilters
Calls the <code>clearFilters</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### getAllHandlers
Calls the <code>getAllHandlers</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### addHandler
Calls the <code>addHandler</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### removeHandler
Calls the <code>removeHandler</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### clearHandlers
Calls the <code>clearHandlers</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### getFormatter
Calls the <code>getFormatter</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### setFormatter
Calls the <code>setFormatter</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### log
Calls the <code>log</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### trace
Calls the <code>trace</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### debug
Calls the <code>debug</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### info
Calls the <code>info</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### warn
Calls the <code>warn</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### error
Calls the <code>error</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
#### fatal
Calls the <code>fatal</code> method on the default <code>Logger</code> instance
with the provided arguments and returns the result.
**Meta**
* **since**: 1.0.0
### getName
Returns the name of this Logger.
Returns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The name of this Logger.
**Meta**
* **since**: 1.0.0
### setName
Sets the name of this Logger.
#### Parameters
* `name` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The new name.
Returns **[Logger](#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
```javascript
// 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](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### getAllFilters
Returns all of the message filters attached to this Logger.
Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](#messagecallback)** The filter function to add.
#### Examples
```javascript
// 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](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### removeFilter
Removes a message filter from this Logger.
#### Parameters
* `filter` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The filter function to remove.
Returns **[Logger](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### clearFilters
Removes all message filters from this Logger.
Returns **[Logger](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### getAllHandlers
Returns all of the log handlers attached to this Logger.
Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](#messagecallback)** The handler function to add.
#### Examples
```javascript
// log messages to the console.
logger.addHandler((level, msg) => {
console.log(level.name, msg);
});
```
Returns **[Logger](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### removeHandler
Removes a message handler from this Logger.
#### Parameters
* `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** The handler function to remove.
Returns **[Logger](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### clearHandlers
Removes all message handlers from this Logger.
Returns **[Logger](#logger)** This Logger instance.
**Meta**
* **since**: 1.0.0
### getFormatter
Returns the current message formatter.
Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/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](#messagecallback)** The formatter function to use to format messages.
#### Examples
```javascript
// prefix the level name.
logger.setFormatter((level, msg) => {
return level.name + ":" + msg;
});
logger.info("hello"); // => logs "info:hello"
```
Returns **[Logger](#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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | Level)** The message level.
* `msg` **...any** The message parameters.
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### trace
Logs a message with the <code>Level.TRACE</code> 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 <code>log(Level.TRACE, msg)</code>
#### Parameters
* `msg` **...any** The message parameters.
#### Examples
```javascript
trace("data");
```
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### debug
Logs a message with the <code>Level.DEBUG</code> 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 <code>log(Level.DEBUG, msg)</code>
#### Parameters
* `msg` **...any** The message parameters.
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### info
Logs a message with the <code>Level.INFO</code> 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 <code>log(Level.INFO, msg)</code>
#### Parameters
* `msg` **...any** The message parameters.
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### warn
Logs a message with the <code>Level.WARN</code> 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 <code>log(Level.WARN, msg)</code>
#### Parameters
* `msg` **...any** The message parameters.
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### error
Logs a message with the <code>Level.ERROR</code> 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 <code>log(Level.ERROR, msg)</code>
#### Parameters
* `msg` **...any** The message parameters.
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### fatal
Logs a message with the <code>Level.FATAL</code> 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 <code>log(Level.FATAL, msg)</code>
#### Parameters
* `msg` **...any** The message parameters.
Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** <code>true</code> if the message is logged, <code>false</code> otherwise.
**Meta**
* **since**: 1.0.0
### messageCallback
Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)
#### Parameters
* `level` **Level** The severity level of the message.
* `msg` **...any** The message parameters.
### Level
The <code>Level</code> 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 <code>Level</code> object by the name or value. If no match is found in the <code>Level.values</code>, undefined is returned.
##### Parameters
* `nameOrValue` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number))** The name or the value of the <code>Level</code> object to get.
Returns **Level** The <code>Level</code> object that has the name or the value if found; undefined otherwise.
**Meta**
* **since**: 1.0.0
#### below
Returns a <code>Level</code> object that is one level below the specified level. If no match is found in the <code>Level.values</code>, undefined is returned.
##### Parameters
* `nameOrValue` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | Level)** The name or value of the level to find the one level below.
Returns **(Level | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))** The <code>Level</code> object that is one level below the specified level if found; undefined otherwise.
**Meta**
* **since**: 1.0.0
#### above
Returns a <code>Level</code> object that is one level above the specified level. If no match is found in the <code>Level.values</code>, undefined is returned.
##### Parameters
* `nameOrValue` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | Level)** The name or value of the level to find the one level above.
Returns **(Level | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))** The <code>Level</code> object that is one level above the specified level if found; undefined otherwise.
**Meta**
* **since**: 1.0.0