]> git.r.bdr.sh - rbdr/cologne/blame - doc/README.md
Add a License
[rbdr/cologne] / doc / README.md
CommitLineData
8b25c581
RBR
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
43Main interface for Cologne Loggers
44
45**Kind**: global interface
46<a name="ILogger.log"></a>
47
48### ILogger.log()
49Receives 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
55Main interface for Cologne Formatters
56
57**Kind**: global interface
58<a name="IFormatter.format"></a>
59
60### IFormatter.format(logObject) ⇒ <code>string</code>
61Receives 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()
92The main logger class. It can be instantiated with loggers in order to
93send messages to different destinations.
94
95<a name="Cologne+from"></a>
96
97### cologne.from : <code>String</code>
98The name of this logger, useful to distinguish between different
99loggers.
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)
106The 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)
113Adds 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)
124Removes 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)
136Given a message, it builds a cologne log object without logging it.
137If you send a cologne log object, it will only update the level.
138
139If the message is an object, the log object will be extended with
140its 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()
153Default log function. Sends arguments to loggers. If not specified in log
154object, 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()
160Logs with debug level
161
162**Kind**: instance method of [<code>Cologne</code>](#Cologne)
163<a name="Cologne+info"></a>
164
165### cologne.info()
166Logs with info level
167
168**Kind**: instance method of [<code>Cologne</code>](#Cologne)
169<a name="Cologne+notice"></a>
170
171### cologne.notice()
172Logs with notice level
173
174**Kind**: instance method of [<code>Cologne</code>](#Cologne)
175<a name="Cologne+warn"></a>
176
177### cologne.warn()
178Logs with warn level
179
180**Kind**: instance method of [<code>Cologne</code>](#Cologne)
181<a name="Cologne+error"></a>
182
183### cologne.error()
184Logs 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()
202Container object for utilities used by loggers.
203
204<a name="Utilities.now"></a>
205
206### Utilities.now() ⇒ <code>bigint</code>
207Returns 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>
214Stringifies 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>
226Given 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>
238Given a level, it will return the appropriate ansi keyword related
239to 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>
251Namespace 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()
281Simple 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>
287Flag that tells us whether or not to use ANSI color. Defaults to
288false.
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>
295Main entry point, it will read the incoming log object and convert
296it 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()
321Token formatter. Given a format string it will attempt to output
322a message.
323
324<a name="Formatters.Token+formatString"></a>
325
326#### token.formatString : <code>String</code>
327The string to use as a template string. By default, any property
328inside double curly braces `{{likeThis}}` will be extracted from
329the object and replaced. If the object does not contain the
330property, 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>
337The 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>
344Flag 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>
352Main entry point, it will read the incoming log object and convert
353all the tokens to their corresponding representation, finally
354returning 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>
366Namespace 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()
397Logger for the javascript console.
398
399<a name="Loggers.Console+console"></a>
400
401#### console.console : <code>Object</code>
402The console it will write to, can be any object that looks
403and 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)
410The formatter it will use to output the log. If not present it
411will 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>
418Main entry point, for each incoming argument it will attempt to
419format 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()
437Logger for files.
438
439<a name="Loggers.File+file"></a>
440
441#### file.file : <code>string</code>
442Path 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)
449The formatter it will use to output the log. If not present it
450will 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>
457Main entry point, for each incoming argument it will attempt to
458format 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>
464The 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