git.r.bdr.sh - rbdr/cologne/blob - doc/README.md

   1 ## Classes
   2
   3 <dl>
   4 <dt><a href="#Cologne">Cologne</a></dt>
   5 <dd></dd>
   6 <dt><a href="#Utilities">Utilities</a></dt>
   7 <dd></dd>
   8 </dl>
   9
  10 ## Objects
  11
  12 <dl>
  13 <dt><a href="#Formatters">Formatters</a> : <code>object</code></dt>
  14 <dd><p>Namespace that includes the built-in formatters.</p>
  15 </dd>
  16 <dt><a href="#Loggers">Loggers</a> : <code>object</code></dt>
  17 <dd><p>Namespace that includes the built-in loggers.</p>
  18 </dd>
  19 </dl>
  20
  21 ## Typedefs
  22
  23 <dl>
  24 <dt><a href="#tCologneLog">tCologneLog</a> : <code>object</code></dt>
  25 <dd><p>The main cologne log format.</p>
  26 </dd>
  27 </dl>
  28
  29 ## Interfaces
  30
  31 <dl>
  32 <dt><a href="#ILogger">ILogger</a></dt>
  33 <dd><p>Main interface for Cologne Loggers</p>
  34 </dd>
  35 <dt><a href="#IFormatter">IFormatter</a></dt>
  36 <dd><p>Main interface for Cologne Formatters</p>
  37 </dd>
  38 </dl>
  39
  40 <a name="ILogger"></a>
  41
  42 ## ILogger
  43 Main interface for Cologne Loggers
  44
  45 **Kind**: global interface
  46 <a name="ILogger.log"></a>
  47
  48 ### ILogger.log()
  49 Receives any number of cologne log objects and logs them.
  50
  51 **Kind**: static method of [<code>ILogger</code>](#ILogger)
  52 <a name="IFormatter"></a>
  53
  54 ## IFormatter
  55 Main interface for Cologne Formatters
  56
  57 **Kind**: global interface
  58 <a name="IFormatter.format"></a>
  59
  60 ### IFormatter.format(logObject) ⇒ <code>string</code>
  61 Receives a cologne log object and returns a formatted string.
  62
  63 **Kind**: static method of [<code>IFormatter</code>](#IFormatter)
  64 **Returns**: <code>string</code> - the formatted log
  65
  66 | Param | Type | Description |
  67 | --- | --- | --- |
  68 | logObject | [<code>tCologneLog</code>](#tCologneLog) | the log to be formatted |
  69
  70 <a name="Cologne"></a>
  71
  72 ## Cologne
  73 **Kind**: global class
  74
  75 * [Cologne](#Cologne)
  76     * [new Cologne()](#new_Cologne_new)
  77     * [.from](#Cologne+from) : <code>String</code>
  78     * [.loggers](#Cologne+loggers) : [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
  79     * [.addLogger(logger)](#Cologne+addLogger)
  80     * [.removeLogger(logger)](#Cologne+removeLogger) ⇒ [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
  81     * [.buildLog(message, [level])](#Cologne+buildLog) ⇒ [<code>tCologneLog</code>](#tCologneLog)
  82     * [.log()](#Cologne+log)
  83     * [.debug()](#Cologne+debug)
  84     * [.info()](#Cologne+info)
  85     * [.notice()](#Cologne+notice)
  86     * [.warn()](#Cologne+warn)
  87     * [.error()](#Cologne+error)
  88
  89 <a name="new_Cologne_new"></a>
  90
  91 ### new Cologne()
  92 The main logger class. It can be instantiated with loggers in order to
  93 send messages to different destinations.
  94
  95 <a name="Cologne+from"></a>
  96
  97 ### cologne.from : <code>String</code>
  98 The name of this logger, useful to distinguish between different
  99 loggers.
 100
 101 **Kind**: instance property of [<code>Cologne</code>](#Cologne)
 102 **Default**: <code>&#x27;Generic Cologne Logger</code>
 103 <a name="Cologne+loggers"></a>
 104
 105 ### cologne.loggers : [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
 106 The array containing all the loggers it will call to.
 107
 108 **Kind**: instance property of [<code>Cologne</code>](#Cologne)
 109 **Default**: <code>[]</code>
 110 <a name="Cologne+addLogger"></a>
 111
 112 ### cologne.addLogger(logger)
 113 Adds a logger to the current instance.
 114
 115 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 116
 117 | Param | Type | Description |
 118 | --- | --- | --- |
 119 | logger | [<code>ILogger</code>](#ILogger) | the logger to add |
 120
 121 <a name="Cologne+removeLogger"></a>
 122
 123 ### cologne.removeLogger(logger) ⇒ [<code>Array.&lt;ILogger&gt;</code>](#ILogger)
 124 Removes a logger from the current instance.
 125
 126 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 127 **Returns**: [<code>Array.&lt;ILogger&gt;</code>](#ILogger) - the removed log, inside an array.
 128
 129 | Param | Type | Description |
 130 | --- | --- | --- |
 131 | logger | [<code>ILogger</code>](#ILogger) | the logger to remove |
 132
 133 <a name="Cologne+buildLog"></a>
 134
 135 ### cologne.buildLog(message, [level]) ⇒ [<code>tCologneLog</code>](#tCologneLog)
 136 Given a message, it builds a cologne log object without logging it.
 137 If you send a cologne log object, it will only update the level.
 138
 139 If the message is an object, the log object will be extended with
 140 its properties.
 141
 142 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 143 **Returns**: [<code>tCologneLog</code>](#tCologneLog) - a cologne log object
 144
 145 | Param | Type | Default | Description |
 146 | --- | --- | --- | --- |
 147 | message | <code>\*</code> |  | The message to log |
 148 | [level] | <code>number</code> | <code>6</code> | The level of the message to log |
 149
 150 <a name="Cologne+log"></a>
 151
 152 ### cologne.log()
 153 Default log function. Sends arguments to loggers. If not specified in log
 154 object, it will set the severity to 6 - INFO.
 155
 156 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 157 <a name="Cologne+debug"></a>
 158
 159 ### cologne.debug()
 160 Logs with debug level
 161
 162 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 163 <a name="Cologne+info"></a>
 164
 165 ### cologne.info()
 166 Logs with info level
 167
 168 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 169 <a name="Cologne+notice"></a>
 170
 171 ### cologne.notice()
 172 Logs with notice level
 173
 174 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 175 <a name="Cologne+warn"></a>
 176
 177 ### cologne.warn()
 178 Logs with warn level
 179
 180 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 181 <a name="Cologne+error"></a>
 182
 183 ### cologne.error()
 184 Logs with error level
 185
 186 **Kind**: instance method of [<code>Cologne</code>](#Cologne)
 187 <a name="Utilities"></a>
 188
 189 ## Utilities
 190 **Kind**: global class
 191
 192 * [Utilities](#Utilities)
 193     * [new Utilities()](#new_Utilities_new)
 194     * [.now()](#Utilities.now) ⇒ <code>bigint</code>
 195     * [.stringify(object)](#Utilities.stringify) ⇒ <code>String</code>
 196     * [.getAnsiCode(ansiString)](#Utilities.getAnsiCode) ⇒ <code>String</code>
 197     * [.getLevelAnsi(level)](#Utilities.getLevelAnsi) ⇒ <code>String</code>
 198
 199 <a name="new_Utilities_new"></a>
 200
 201 ### new Utilities()
 202 Container object for utilities used by loggers.
 203
 204 <a name="Utilities.now"></a>
 205
 206 ### Utilities.now() ⇒ <code>bigint</code>
 207 Returns the current timestamp in nanoseconds as a bigint.
 208
 209 **Kind**: static method of [<code>Utilities</code>](#Utilities)
 210 **Returns**: <code>bigint</code> - current time in nanoseconds, including fractions.
 211 <a name="Utilities.stringify"></a>
 212
 213 ### Utilities.stringify(object) ⇒ <code>String</code>
 214 Stringifies objects, avoiding circular references.
 215
 216 **Kind**: static method of [<code>Utilities</code>](#Utilities)
 217 **Returns**: <code>String</code> - the stringified object
 218
 219 | Param | Type | Description |
 220 | --- | --- | --- |
 221 | object | <code>Object</code> | the object to stringify |
 222
 223 <a name="Utilities.getAnsiCode"></a>
 224
 225 ### Utilities.getAnsiCode(ansiString) ⇒ <code>String</code>
 226 Given an ansi keyword, it will return the appropriate code.
 227
 228 **Kind**: static method of [<code>Utilities</code>](#Utilities)
 229 **Returns**: <code>String</code> - the ansi code
 230
 231 | Param | Type | Description |
 232 | --- | --- | --- |
 233 | ansiString | <code>String</code> | the name of the desired code |
 234
 235 <a name="Utilities.getLevelAnsi"></a>
 236
 237 ### Utilities.getLevelAnsi(level) ⇒ <code>String</code>
 238 Given a level, it will return the appropriate ansi keyword related
 239 to it.
 240
 241 **Kind**: static method of [<code>Utilities</code>](#Utilities)
 242 **Returns**: <code>String</code> - the ansi keyword
 243
 244 | Param | Type | Description |
 245 | --- | --- | --- |
 246 | level | <code>number</code> | the level of the log |
 247
 248 <a name="Formatters"></a>
 249
 250 ## Formatters : <code>object</code>
 251 Namespace that includes the built-in formatters.
 252
 253 **Kind**: global namespace
 254
 255 * [Formatters](#Formatters) : <code>object</code>
 256     * [.Simple](#Formatters.Simple)
 257         * [new Simple()](#new_Formatters.Simple_new)
 258         * [.colorize](#Formatters.Simple+colorize) : <code>Boolean</code>
 259         * [.format(logObjet)](#Formatters.Simple+format) ⇒ <code>String</code>
 260     * [.Token](#Formatters.Token)
 261         * [new Token()](#new_Formatters.Token_new)
 262         * [.formatString](#Formatters.Token+formatString) : <code>String</code>
 263         * [.replaceRule](#Formatters.Token+replaceRule) : <code>RegExp</code>
 264         * [.isoDate](#Formatters.Token+isoDate) : <code>Boolean</code>
 265         * [.format(log)](#Formatters.Token+format) ⇒ <code>String</code>
 266
 267 <a name="Formatters.Simple"></a>
 268
 269 ### Formatters.Simple
 270 **Kind**: static class of [<code>Formatters</code>](#Formatters)
 271 **Implements**: [<code>IFormatter</code>](#IFormatter)
 272
 273 * [.Simple](#Formatters.Simple)
 274     * [new Simple()](#new_Formatters.Simple_new)
 275     * [.colorize](#Formatters.Simple+colorize) : <code>Boolean</code>
 276     * [.format(logObjet)](#Formatters.Simple+format) ⇒ <code>String</code>
 277
 278 <a name="new_Formatters.Simple_new"></a>
 279
 280 #### new Simple()
 281 Simple formatter. Outputs a predefined format:
 282 `[{{_timestamp}}][{{_levelString}}] {{_from}}: {{message}}`;
 283
 284 <a name="Formatters.Simple+colorize"></a>
 285
 286 #### simple.colorize : <code>Boolean</code>
 287 Flag that tells us whether or not to use ANSI color. Defaults to
 288 false.
 289
 290 **Kind**: instance property of [<code>Simple</code>](#Formatters.Simple)
 291 **Default**: <code>false</code>
 292 <a name="Formatters.Simple+format"></a>
 293
 294 #### simple.format(logObjet) ⇒ <code>String</code>
 295 Main entry point, it will read the incoming log object and convert
 296 it to the output string.
 297
 298 **Kind**: instance method of [<code>Simple</code>](#Formatters.Simple)
 299 **Returns**: <code>String</code> - the formatted object
 300
 301 | Param | Type | Description |
 302 | --- | --- | --- |
 303 | logObjet | [<code>tCologneLog</code>](#tCologneLog) | the log to format |
 304
 305 <a name="Formatters.Token"></a>
 306
 307 ### Formatters.Token
 308 **Kind**: static class of [<code>Formatters</code>](#Formatters)
 309 **Implements**: [<code>IFormatter</code>](#IFormatter)
 310
 311 * [.Token](#Formatters.Token)
 312     * [new Token()](#new_Formatters.Token_new)
 313     * [.formatString](#Formatters.Token+formatString) : <code>String</code>
 314     * [.replaceRule](#Formatters.Token+replaceRule) : <code>RegExp</code>
 315     * [.isoDate](#Formatters.Token+isoDate) : <code>Boolean</code>
 316     * [.format(log)](#Formatters.Token+format) ⇒ <code>String</code>
 317
 318 <a name="new_Formatters.Token_new"></a>
 319
 320 #### new Token()
 321 Token formatter. Given a format string it will attempt to output
 322 a message.
 323
 324 <a name="Formatters.Token+formatString"></a>
 325
 326 #### token.formatString : <code>String</code>
 327 The string to use as a template string. By default, any property
 328 inside double curly braces `{{likeThis}}` will be extracted from
 329 the object and replaced. If the object does not contain the
 330 property, it will leave it.
 331
 332 **Kind**: instance property of [<code>Token</code>](#Formatters.Token)
 333 **Default**: <code>&#x27;{{message}}&#x27;</code>
 334 <a name="Formatters.Token+replaceRule"></a>
 335
 336 #### token.replaceRule : <code>RegExp</code>
 337 The regex rule to use to match the tokens.
 338
 339 **Kind**: instance property of [<code>Token</code>](#Formatters.Token)
 340 **Default**: <code>/{{(.*)}}/g</code>
 341 <a name="Formatters.Token+isoDate"></a>
 342
 343 #### token.isoDate : <code>Boolean</code>
 344 Flag that specifies whether or not to use an isoDate when using
 345 `_timestamp`. If false it will output the raw timestamp.
 346
 347 **Kind**: instance property of [<code>Token</code>](#Formatters.Token)
 348 **Default**: <code>true</code>
 349 <a name="Formatters.Token+format"></a>
 350
 351 #### token.format(log) ⇒ <code>String</code>
 352 Main entry point, it will read the incoming log object and convert
 353 all the tokens to their corresponding representation, finally
 354 returning the string.
 355
 356 **Kind**: instance method of [<code>Token</code>](#Formatters.Token)
 357 **Returns**: <code>String</code> - the formatted object
 358
 359 | Param | Type | Description |
 360 | --- | --- | --- |
 361 | log | [<code>tCologneLog</code>](#tCologneLog) | the log to format |
 362
 363 <a name="Loggers"></a>
 364
 365 ## Loggers : <code>object</code>
 366 Namespace that includes the built-in loggers.
 367
 368 **Kind**: global namespace
 369
 370 * [Loggers](#Loggers) : <code>object</code>
 371     * [.Console](#Loggers.Console)
 372         * [new Console()](#new_Loggers.Console_new)
 373         * [.console](#Loggers.Console+console) : <code>Object</code>
 374         * [.formatter](#Loggers.Console+formatter) : [<code>IFormatter</code>](#IFormatter)
 375         * [.log()](#Loggers.Console+log) ⇒ <code>undefined</code>
 376     * [.File](#Loggers.File)
 377         * [new File()](#new_Loggers.File_new)
 378         * [.file](#Loggers.File+file) : <code>string</code>
 379         * [.formatter](#Loggers.File+formatter) : [<code>IFormatter</code>](#IFormatter)
 380         * [.log()](#Loggers.File+log) ⇒ <code>undefined</code>
 381
 382 <a name="Loggers.Console"></a>
 383
 384 ### Loggers.Console
 385 **Kind**: static class of [<code>Loggers</code>](#Loggers)
 386 **Implements**: [<code>ILogger</code>](#ILogger)
 387
 388 * [.Console](#Loggers.Console)
 389     * [new Console()](#new_Loggers.Console_new)
 390     * [.console](#Loggers.Console+console) : <code>Object</code>
 391     * [.formatter](#Loggers.Console+formatter) : [<code>IFormatter</code>](#IFormatter)
 392     * [.log()](#Loggers.Console+log) ⇒ <code>undefined</code>
 393
 394 <a name="new_Loggers.Console_new"></a>
 395
 396 #### new Console()
 397 Logger for the javascript console.
 398
 399 <a name="Loggers.Console+console"></a>
 400
 401 #### console.console : <code>Object</code>
 402 The console it will write to, can be any object that looks
 403 and acts like a console, including other cologne objects.
 404
 405 **Kind**: instance property of [<code>Console</code>](#Loggers.Console)
 406 **Default**: <code>global.console</code>
 407 <a name="Loggers.Console+formatter"></a>
 408
 409 #### console.formatter : [<code>IFormatter</code>](#IFormatter)
 410 The formatter it will use to output the log. If not present it
 411 will output raw JSON
 412
 413 **Kind**: instance property of [<code>Console</code>](#Loggers.Console)
 414 **Default**: <code>null</code>
 415 <a name="Loggers.Console+log"></a>
 416
 417 #### console.log() ⇒ <code>undefined</code>
 418 Main entry point, for each incoming argument it will attempt to
 419 format and send to the console.
 420
 421 **Kind**: instance method of [<code>Console</code>](#Loggers.Console)
 422 <a name="Loggers.File"></a>
 423
 424 ### Loggers.File
 425 **Kind**: static class of [<code>Loggers</code>](#Loggers)
 426 **Implements**: [<code>ILogger</code>](#ILogger)
 427
 428 * [.File](#Loggers.File)
 429     * [new File()](#new_Loggers.File_new)
 430     * [.file](#Loggers.File+file) : <code>string</code>
 431     * [.formatter](#Loggers.File+formatter) : [<code>IFormatter</code>](#IFormatter)
 432     * [.log()](#Loggers.File+log) ⇒ <code>undefined</code>
 433
 434 <a name="new_Loggers.File_new"></a>
 435
 436 #### new File()
 437 Logger for files.
 438
 439 <a name="Loggers.File+file"></a>
 440
 441 #### file.file : <code>string</code>
 442 Path to the file it will write to, must be readable.
 443
 444 **Kind**: instance property of [<code>File</code>](#Loggers.File)
 445 **Default**: <code>&quot;null&quot;</code>
 446 <a name="Loggers.File+formatter"></a>
 447
 448 #### file.formatter : [<code>IFormatter</code>](#IFormatter)
 449 The formatter it will use to output the log. If not present it
 450 will output raw JSON
 451
 452 **Kind**: instance property of [<code>File</code>](#Loggers.File)
 453 **Default**: <code>null</code>
 454 <a name="Loggers.File+log"></a>
 455
 456 #### file.log() ⇒ <code>undefined</code>
 457 Main entry point, for each incoming argument it will attempt to
 458 format and send to the stream to be written.
 459
 460 **Kind**: instance method of [<code>File</code>](#Loggers.File)
 461 <a name="tCologneLog"></a>
 462
 463 ## tCologneLog : <code>object</code>
 464 The main cologne log format.
 465
 466 **Kind**: global typedef
 467 **Properties**
 468
 469 | Name | Type | Description |
 470 | --- | --- | --- |
 471 | _timestamp | <code>Bigint</code> | the timestamp in nanoseconds |
 472 | _cologneLog | <code>String</code> | main identifier, encodes the version of the cologne log format being used. |
 473 | _from | <code>String</code> | the origin of the log message. |
 474 | _level | <code>String</code> | the severity level of the log, uses syslog priorities. |
 475 | _levelString | <code>String</code> | the severity level keyword of the log, uses syslog priority keywords. |
 476