Run lint and test on merge requests

[rbdr/cologne] / doc / README.md

## Classes

<dl>
<dt><a href="#Cologne">Cologne</a></dt>
<dd></dd>
<dt><a href="#Utilities">Utilities</a></dt>
<dd></dd>
</dl>

## Objects

<dl>
<dt><a href="#Formatters">Formatters</a> : <code>object</code></dt>
<dd><p>Namespace that includes the built-in formatters.</p>
</dd>
<dt><a href="#Loggers">Loggers</a> : <code>object</code></dt>
<dd><p>Namespace that includes the built-in loggers.</p>
</dd>
</dl>

## Typedefs

<dl>
<dt><a href="#tCologneLog">tCologneLog</a> : <code>object</code></dt>
<dd><p>The main cologne log format.</p>
</dd>
</dl>

## Interfaces

<dl>
<dt><a href="#ILogger">ILogger</a></dt>
<dd><p>Main interface for Cologne Loggers</p>
</dd>
<dt><a href="#IFormatter">IFormatter</a></dt>
<dd><p>Main interface for Cologne Formatters</p>
</dd>
</dl>

<a name="ILogger"></a>

## ILogger
Main interface for Cologne Loggers

**Kind**: global interface  
<a name="ILogger.log"></a>

### ILogger.log()
Receives any number of cologne log objects and logs them.

**Kind**: static method of [<code>ILogger</code>](#ILogger)  
<a name="IFormatter"></a>

## IFormatter
Main interface for Cologne Formatters

**Kind**: global interface  
<a name="IFormatter.format"></a>

### IFormatter.format(logObject) ⇒ <code>string</code>
Receives a cologne log object and returns a formatted string.

**Kind**: static method of [<code>IFormatter</code>](#IFormatter)  
**Returns**: <code>string</code> - the formatted log  

| Param | Type | Description |
| --- | --- | --- |
| logObject | [<code>tCologneLog</code>](#tCologneLog) | the log to be formatted |

<a name="Cologne"></a>

## Cologne
**Kind**: global class  

* [Cologne](#Cologne)
    * [new Cologne()](#new_Cologne_new)
    * [.from](#Cologne+from) : <code>String</code>
    * [.loggers](#Cologne+loggers) : [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
    * [.addLogger(logger)](#Cologne+addLogger)
    * [.removeLogger(logger)](#Cologne+removeLogger) ⇒ [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
    * [.buildLog(message, [level])](#Cologne+buildLog) ⇒ [<code>tCologneLog</code>](#tCologneLog)
    * [.log()](#Cologne+log)
    * [.debug()](#Cologne+debug)
    * [.info()](#Cologne+info)
    * [.notice()](#Cologne+notice)
    * [.warn()](#Cologne+warn)
    * [.error()](#Cologne+error)

<a name="new_Cologne_new"></a>

### new Cologne()
The main logger class. It can be instantiated with loggers in order to
send messages to different destinations.

<a name="Cologne+from"></a>

### cologne.from : <code>String</code>
The name of this logger, useful to distinguish between different
loggers.

**Kind**: instance property of [<code>Cologne</code>](#Cologne)  
**Default**: <code>&#x27;Generic Cologne Logger</code>  
<a name="Cologne+loggers"></a>

### cologne.loggers : [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
The array containing all the loggers it will call to.

**Kind**: instance property of [<code>Cologne</code>](#Cologne)  
**Default**: <code>[]</code>  
<a name="Cologne+addLogger"></a>

### cologne.addLogger(logger)
Adds a logger to the current instance.

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  

| Param | Type | Description |
| --- | --- | --- |
| logger | [<code>ILogger</code>](#ILogger) | the logger to add |

<a name="Cologne+removeLogger"></a>

### cologne.removeLogger(logger) ⇒ [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
Removes a logger from the current instance.

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
**Returns**: [<code>Array.&lt;ILogger&gt;</code>](#ILogger) - the removed log, inside an array.  

| Param | Type | Description |
| --- | --- | --- |
| logger | [<code>ILogger</code>](#ILogger) | the logger to remove |

<a name="Cologne+buildLog"></a>

### cologne.buildLog(message, [level]) ⇒ [<code>tCologneLog</code>](#tCologneLog)
Given a message, it builds a cologne log object without logging it.
If you send a cologne log object, it will only update the level.

If the message is an object, the log object will be extended with
its properties.

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
**Returns**: [<code>tCologneLog</code>](#tCologneLog) - a cologne log object  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | <code>\*</code> |  | The message to log |
| [level] | <code>number</code> | <code>6</code> | The level of the message to log |

<a name="Cologne+log"></a>

### cologne.log()
Default log function. Sends arguments to loggers. If not specified in log
object, it will set the severity to 6 - INFO.

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
<a name="Cologne+debug"></a>

### cologne.debug()
Logs with debug level

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
<a name="Cologne+info"></a>

### cologne.info()
Logs with info level

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
<a name="Cologne+notice"></a>

### cologne.notice()
Logs with notice level

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
<a name="Cologne+warn"></a>

### cologne.warn()
Logs with warn level

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
<a name="Cologne+error"></a>

### cologne.error()
Logs with error level

**Kind**: instance method of [<code>Cologne</code>](#Cologne)  
<a name="Utilities"></a>

## Utilities
**Kind**: global class  

* [Utilities](#Utilities)
    * [new Utilities()](#new_Utilities_new)
    * [.now()](#Utilities.now) ⇒ <code>bigint</code>
    * [.stringify(object)](#Utilities.stringify) ⇒ <code>String</code>
    * [.getAnsiCode(ansiString)](#Utilities.getAnsiCode) ⇒ <code>String</code>
    * [.getLevelAnsi(level)](#Utilities.getLevelAnsi) ⇒ <code>String</code>

<a name="new_Utilities_new"></a>

### new Utilities()
Container object for utilities used by loggers.

<a name="Utilities.now"></a>

### Utilities.now() ⇒ <code>bigint</code>
Returns the current timestamp in nanoseconds as a bigint.

**Kind**: static method of [<code>Utilities</code>](#Utilities)  
**Returns**: <code>bigint</code> - current time in nanoseconds, including fractions.  
<a name="Utilities.stringify"></a>

### Utilities.stringify(object) ⇒ <code>String</code>
Stringifies objects, avoiding circular references.

**Kind**: static method of [<code>Utilities</code>](#Utilities)  
**Returns**: <code>String</code> - the stringified object  

| Param | Type | Description |
| --- | --- | --- |
| object | <code>Object</code> | the object to stringify |

<a name="Utilities.getAnsiCode"></a>

### Utilities.getAnsiCode(ansiString) ⇒ <code>String</code>
Given an ansi keyword, it will return the appropriate code.

**Kind**: static method of [<code>Utilities</code>](#Utilities)  
**Returns**: <code>String</code> - the ansi code  

| Param | Type | Description |
| --- | --- | --- |
| ansiString | <code>String</code> | the name of the desired code |

<a name="Utilities.getLevelAnsi"></a>

### Utilities.getLevelAnsi(level) ⇒ <code>String</code>
Given a level, it will return the appropriate ansi keyword related
to it.

**Kind**: static method of [<code>Utilities</code>](#Utilities)  
**Returns**: <code>String</code> - the ansi keyword  

| Param | Type | Description |
| --- | --- | --- |
| level | <code>number</code> | the level of the log |

<a name="Formatters"></a>

## Formatters : <code>object</code>
Namespace that includes the built-in formatters.

**Kind**: global namespace  

* [Formatters](#Formatters) : <code>object</code>
    * [.Simple](#Formatters.Simple)
        * [new Simple()](#new_Formatters.Simple_new)
        * [.colorize](#Formatters.Simple+colorize) : <code>Boolean</code>
        * [.format(logObjet)](#Formatters.Simple+format) ⇒ <code>String</code>
    * [.Token](#Formatters.Token)
        * [new Token()](#new_Formatters.Token_new)
        * [.formatString](#Formatters.Token+formatString) : <code>String</code>
        * [.replaceRule](#Formatters.Token+replaceRule) : <code>RegExp</code>
        * [.isoDate](#Formatters.Token+isoDate) : <code>Boolean</code>
        * [.format(log)](#Formatters.Token+format) ⇒ <code>String</code>

<a name="Formatters.Simple"></a>

### Formatters.Simple
**Kind**: static class of [<code>Formatters</code>](#Formatters)  
**Implements**: [<code>IFormatter</code>](#IFormatter)  

* [.Simple](#Formatters.Simple)
    * [new Simple()](#new_Formatters.Simple_new)
    * [.colorize](#Formatters.Simple+colorize) : <code>Boolean</code>
    * [.format(logObjet)](#Formatters.Simple+format) ⇒ <code>String</code>

<a name="new_Formatters.Simple_new"></a>

#### new Simple()
Simple formatter. Outputs a predefined format:
`[{{_timestamp}}][{{_levelString}}] {{_from}}: {{message}}`;

<a name="Formatters.Simple+colorize"></a>

#### simple.colorize : <code>Boolean</code>
Flag that tells us whether or not to use ANSI color. Defaults to
false.

**Kind**: instance property of [<code>Simple</code>](#Formatters.Simple)  
**Default**: <code>false</code>  
<a name="Formatters.Simple+format"></a>

#### simple.format(logObjet) ⇒ <code>String</code>
Main entry point, it will read the incoming log object and convert
it to the output string.

**Kind**: instance method of [<code>Simple</code>](#Formatters.Simple)  
**Returns**: <code>String</code> - the formatted object  

| Param | Type | Description |
| --- | --- | --- |
| logObjet | [<code>tCologneLog</code>](#tCologneLog) | the log to format |

<a name="Formatters.Token"></a>

### Formatters.Token
**Kind**: static class of [<code>Formatters</code>](#Formatters)  
**Implements**: [<code>IFormatter</code>](#IFormatter)  

* [.Token](#Formatters.Token)
    * [new Token()](#new_Formatters.Token_new)
    * [.formatString](#Formatters.Token+formatString) : <code>String</code>
    * [.replaceRule](#Formatters.Token+replaceRule) : <code>RegExp</code>
    * [.isoDate](#Formatters.Token+isoDate) : <code>Boolean</code>
    * [.format(log)](#Formatters.Token+format) ⇒ <code>String</code>

<a name="new_Formatters.Token_new"></a>

#### new Token()
Token formatter. Given a format string it will attempt to output
a message.

<a name="Formatters.Token+formatString"></a>

#### token.formatString : <code>String</code>
The string to use as a template string. By default, any property
inside double curly braces `{{likeThis}}` will be extracted from
the object and replaced. If the object does not contain the
property, it will leave it.

**Kind**: instance property of [<code>Token</code>](#Formatters.Token)  
**Default**: <code>&#x27;{{message}}&#x27;</code>  
<a name="Formatters.Token+replaceRule"></a>

#### token.replaceRule : <code>RegExp</code>
The regex rule to use to match the tokens.

**Kind**: instance property of [<code>Token</code>](#Formatters.Token)  
**Default**: <code>/{{(.*)}}/g</code>  
<a name="Formatters.Token+isoDate"></a>

#### token.isoDate : <code>Boolean</code>
Flag that specifies whether or not to use an isoDate when using
`_timestamp`. If false it will output the raw timestamp.

**Kind**: instance property of [<code>Token</code>](#Formatters.Token)  
**Default**: <code>true</code>  
<a name="Formatters.Token+format"></a>

#### token.format(log) ⇒ <code>String</code>
Main entry point, it will read the incoming log object and convert
all the tokens to their corresponding representation, finally
returning the string.

**Kind**: instance method of [<code>Token</code>](#Formatters.Token)  
**Returns**: <code>String</code> - the formatted object  

| Param | Type | Description |
| --- | --- | --- |
| log | [<code>tCologneLog</code>](#tCologneLog) | the log to format |

<a name="Loggers"></a>

## Loggers : <code>object</code>
Namespace that includes the built-in loggers.

**Kind**: global namespace  

* [Loggers](#Loggers) : <code>object</code>
    * [.Console](#Loggers.Console)
        * [new Console()](#new_Loggers.Console_new)
        * [.console](#Loggers.Console+console) : <code>Object</code>
        * [.formatter](#Loggers.Console+formatter) : [<code>IFormatter</code>](#IFormatter)
        * [.log()](#Loggers.Console+log) ⇒ <code>undefined</code>
    * [.File](#Loggers.File)
        * [new File()](#new_Loggers.File_new)
        * [.file](#Loggers.File+file) : <code>string</code>
        * [.formatter](#Loggers.File+formatter) : [<code>IFormatter</code>](#IFormatter)
        * [.log()](#Loggers.File+log) ⇒ <code>undefined</code>

<a name="Loggers.Console"></a>

### Loggers.Console
**Kind**: static class of [<code>Loggers</code>](#Loggers)  
**Implements**: [<code>ILogger</code>](#ILogger)  

* [.Console](#Loggers.Console)
    * [new Console()](#new_Loggers.Console_new)
    * [.console](#Loggers.Console+console) : <code>Object</code>
    * [.formatter](#Loggers.Console+formatter) : [<code>IFormatter</code>](#IFormatter)
    * [.log()](#Loggers.Console+log) ⇒ <code>undefined</code>

<a name="new_Loggers.Console_new"></a>

#### new Console()
Logger for the javascript console.

<a name="Loggers.Console+console"></a>

#### console.console : <code>Object</code>
The console it will write to, can be any object that looks
and acts like a console, including other cologne objects.

**Kind**: instance property of [<code>Console</code>](#Loggers.Console)  
**Default**: <code>global.console</code>  
<a name="Loggers.Console+formatter"></a>

#### console.formatter : [<code>IFormatter</code>](#IFormatter)
The formatter it will use to output the log. If not present it
will output raw JSON

**Kind**: instance property of [<code>Console</code>](#Loggers.Console)  
**Default**: <code>null</code>  
<a name="Loggers.Console+log"></a>

#### console.log() ⇒ <code>undefined</code>
Main entry point, for each incoming argument it will attempt to
format and send to the console.

**Kind**: instance method of [<code>Console</code>](#Loggers.Console)  
<a name="Loggers.File"></a>

### Loggers.File
**Kind**: static class of [<code>Loggers</code>](#Loggers)  
**Implements**: [<code>ILogger</code>](#ILogger)  

* [.File](#Loggers.File)
    * [new File()](#new_Loggers.File_new)
    * [.file](#Loggers.File+file) : <code>string</code>
    * [.formatter](#Loggers.File+formatter) : [<code>IFormatter</code>](#IFormatter)
    * [.log()](#Loggers.File+log) ⇒ <code>undefined</code>

<a name="new_Loggers.File_new"></a>

#### new File()
Logger for files.

<a name="Loggers.File+file"></a>

#### file.file : <code>string</code>
Path to the file it will write to, must be readable.

**Kind**: instance property of [<code>File</code>](#Loggers.File)  
**Default**: <code>&quot;null&quot;</code>  
<a name="Loggers.File+formatter"></a>

#### file.formatter : [<code>IFormatter</code>](#IFormatter)
The formatter it will use to output the log. If not present it
will output raw JSON

**Kind**: instance property of [<code>File</code>](#Loggers.File)  
**Default**: <code>null</code>  
<a name="Loggers.File+log"></a>

#### file.log() ⇒ <code>undefined</code>
Main entry point, for each incoming argument it will attempt to
format and send to the stream to be written.

**Kind**: instance method of [<code>File</code>](#Loggers.File)  
<a name="tCologneLog"></a>

## tCologneLog : <code>object</code>
The main cologne log format.

**Kind**: global typedef  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| _timestamp | <code>Bigint</code> | the timestamp in nanoseconds |
| _cologneLog | <code>String</code> | main identifier, encodes the version of the cologne log format being used. |
| _from | <code>String</code> | the origin of the log message. |
| _level | <code>String</code> | the severity level of the log, uses syslog priorities. |
| _levelString | <code>String</code> | the severity level keyword of the log, uses syslog priority keywords. |