]> git.r.bdr.sh - rbdr/cologne/blob - doc/README.md
Update the version
[rbdr/cologne] / 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