Another logger in JS. This one offers a console.log-like API and formatting, colored lines and timestamps (or not if desired), all that with 0 dependencies.

Commit 1cd2ef83

1cd2ef838cf7Merged

Maxence Lecanu <[email protected]> · 4 years ago · 2 files · ~1 modified

Description

fix: improve doc

Details

Commit
1cd2ef838cf7
Parent
5a8e3be4850a

README.mdmodifiedView file

@@ -6,6 +6,23 @@
66
77 It offers a `console.log`-like API and formatting, **extensible type-safety** colored lines and timestamps (or not if desired), all that with 0 dependencies.
88
9+1. [Installation](#install)
10+2. [Get started](#get-started)
11+3. [Transports and options](#transport-and-options)
12+ 1. [Console](#console)
13+ 2. [File](#file)
14+4. [Formatters](#formatters)
15+ 1. [Available formatters](#available-formatters)
16+ 2. [Add custom formatters](#custom-formatters)
17+5. [Extensibility](#extensibility)
18+ 1. [Context elaboration](#context-elaboration)
19+ 1. [Presentation](#presentation)
20+ 2. [Message context elaboration](#improve-context-elaboration)
21+ 2. [Transport](#transport)
22+ 1. [Preparation](#preparation)
23+ 2. [Formatting](#formatting)
24+ 3. [Transportation](#transportation)
25+
926 ## Install
1027
1128 ```bash
@@ -136,16 +153,89 @@
136153
137154 Defaults to `"output.log"`, the path to the file where logs are written. Can absolute or relative. However, we recommend using absolute paths.
138155
139-## Extensibilty
156+## Formatters
157+
158+Every transport takes a `formatters` parameter in it's options.
159+
160+```ts
161+const csle = new transports.Console<ExtendedContext>({
162+ // These are the default formatters, and the logger will default to this list
163+ formatters: [
164+ formatters.addLevel(true),
165+ formatters.addTimestamp(),
166+ formatters.colorize(),
167+ ],
168+});
169+
170+const logger = new Hellog<ExtendedContext>({
171+ transports: [csle],
172+});
173+
174+logger.suceess('I hve been formatted !');
175+```
176+
177+### Available formatters
178+
179+#### `addTimestamp`
180+
181+Add the current date at the beginning of the line.
182+
183+```txt
184+2021-12-26 15:20:42 | {
185+2021-12-26 15:20:42 | some: 'bar',
186+2021-12-26 15:20:42 | foo: { nested: { bar: 'test', test: 'bar', hello: 2 } }
187+2021-12-26 15:20:42 | }
188+```
189+
190+#### `addLevel(bold: boolean = true)`
191+
192+Add the log level at the beginning of the line. It can be displayed in bold or not.
193+
194+```ts
195+[info] | {
196+[info] | some: 'bar',
197+[info] | foo: { nested: { bar: 'test', test: 'bar', hello: 2 } }
198+[info] | }
199+```
200+
201+#### `colorize`
202+
203+Appends colorizing escape characters at the beginning and the end of the formatted string, depending on the log level
204+
205+![image](./assets/colorized.png 'Colorized')
206+
207+### Custom formatters
208+
209+You can implement and add custom formatters, as long as they match the `Formatter` signature.
210+
211+```ts
212+type Formatter<T extends PreparedMessage = PreparedMessage> = (
213+ current: string,
214+ context: T
215+) => string;
216+```
217+
218+**Example:** A simple formatter that will insert a hello message at the beginning of the log
140219
220+```ts
221+const exampleFormatter = (current: string, context: PreparedMessage) {
222+ return "hello " + current
223+}
224+```
225+
226+> Before extending `PreparedMessage` in your formatter declaration, you should read the [Extensibility section](#extensibility)
227+
228+## Extensibility
229+
141230 The logging functionalities of `Hellog` are designed to be extensible. You can add personalized behaviour to the following elements of the logger:
142231
143-- Message context elaboration
144-- Message formatting on a per-transport basis
232+- [Message context elaboration](#improve-context-elaboration)
233+- Message transportation
234+ - [Preparation](#preparation)
235+ - [Formatting](#formatting)
236+ - [Transportation](#transportation)
145237
146238 Hellog is also designed to guarantee type-safety even with your custom implementations !
147-
148-### Life cycle
149239
150240 To better understand where you can perform custom logic, let's quickly review the lifecycle of a message within the logger.
151241
@@ -155,7 +245,9 @@
155245 new Hellog().log({ foo: bar }, 'Hello world');
156246 ```
157247
158-#### **Context elaboration**
248+### Context elaboration
249+
250+#### Presentation
159251
160252 The very first thing done by `Hellog` is converting these inputs into a string.
161253
@@ -191,7 +283,49 @@
191283 }
192284 ```
193285
194-#### **Transport preparation**
286+#### Improve context elaboration
287+
288+If you need to add additional data into the `PreparedMessage` object being passed along this cycle, you can using the `additionalContext` when instanciating the `Hellog` object.
289+
290+You can even do it with type safety and completion !
291+
292+```ts
293+import { Hellog } from './logger';
294+
295+interface ExtendedContext extends PreparedMessage {
296+ id: number;
297+}
298+
299+const displayId: Formatter<ExtendedContext> = (
300+ current: string,
301+ context: ExtendedContext
302+) => {
303+ return `${context.id} | ${current}`;
304+};
305+
306+const csle = new transports.Console<ExtendedContext>({
307+ formatters: [
308+ formatters.addLevel(true),
309+ displayId,
310+ formatters.addTimestamp(),
311+ formatters.colorize(),
312+ ],
313+});
314+
315+const logger = new Hellog<ExtendedContext>({
316+ transports: [csle],
317+ additionalContext: (message) => ({
318+ ...message,
319+ id: Math.floor(Math.random() * 1000),
320+ }),
321+});
322+
323+logger.error(new Error('test'));
324+```
325+
326+### Transport
327+
328+#### Preparation
195329
196330 In `Hellog`, messages are formatted and displayed on a _per-line_ basis. Meaning here that if your log spans on mutliple lines, it is breaked into a list of lines on the `"\n"` character.
197331
@@ -217,9 +351,11 @@
217351
218352 Here, we don't want to break line when outputting JSON message, this is left to any system that will monitor this and read the log file.
219353
220-**Each input in the resulting list is passed to the `format` method.**
354+**Each input in the resulting list is passed to the `format` method of the transport.**
355+
356+#### Formatting
221357
222-#### **Formatting**
358+> _This section is about extending the formatting logic. See here for [Custom Formatters](#custom-formatters)_
223359
224360 Formatting is performed on a **per-line** basis. Each transport is instanciated with a list of formatters, that extends the Formatter type.
225361
@@ -254,52 +390,10 @@
254390 }
255391 ```
256392
257-> You can override this behaviour when doing your own transport class.
393+**You can override this behaviour when doing your own transport class.**
258394
259-#### Message transportation
395+#### Transportation
260396
261397 Once the log is nothing more than a list of string, the `transport` method of the transport is called for each resulting string.
262398
263399 Very various thing happen at this point. by default, a simple `console.log` is performed here. The `FileTransport` writes into a `fs.WriteStream`. You can implement a transport where the lines are sent over HTTP. [Here are some examples](https://www.youtube.com/watch?v=1MkzF9cFs2I).
264-
265-### Improve formatting
266-
267-### Improve context elaboration
268-
269-If you need to add additional data into the `PreparedMessage` object being passed along this cycle, you can using the `additionalContext` when instanciating the `Hellog` object.
270-
271-You can even do it with type safety and completion !
272-
273-```ts
274-import { Hellog } from './logger';
275-
276-interface ExtendedContext extends PreparedMessage {
277- id: number;
278-}
279-
280-const displayId: Formatter<ExtendedContext> = (
281- current: string,
282- context: ExtendedContext
283-) => {
284- return `${context.id} | ${current}`;
285-};
286-
287-const csle = new transports.Console<ExtendedContext>({
288- formatters: [
289- formatters.addLevel(true),
290- displayId,
291- formatters.addTimestamp(),
292- formatters.colorize(),
293- ],
294-});
295-
296-const logger = new Hellog<ExtendedContext>({
297- transports: [csle],
298- additionalContext: (message) => ({
299- ...message,
300- id: Math.floor(Math.random() * 1000),
301- }),
302-});
303-
304-logger.success(new Error('test'));
305-```