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
## Install1027
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-
## Extensibilty156+
## Formatters157+
158+
Every transport takes a `formatters` parameter in it's options.159+
160+
```ts161+
const csle = new transports.Console<ExtendedContext>({162+
// These are the default formatters, and the logger will default to this list163+
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 formatters178+
179+
#### `addTimestamp`180+
181+
Add the current date at the beginning of the line.182+
183+
```txt184+
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+
```ts195+
[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 level204+
205+
206+
207+
### Custom formatters208+
209+
You can implement and add custom formatters, as long as they match the `Formatter` signature.210+
211+
```ts212+
type Formatter<T extends PreparedMessage = PreparedMessage> = (213+
current: string,214+
context: T215+
) => string;216+
```217+
218+
**Example:** A simple formatter that will insert a hello message at the beginning of the log140219
220+
```ts221+
const exampleFormatter = (current: string, context: PreparedMessage) {222+
return "hello " + current223+
}224+
```225+
226+
> Before extending `PreparedMessage` in your formatter declaration, you should read the [Extensibility section](#extensibility)227+
228+
## Extensibility229+
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 elaboration144-
- Message formatting on a per-transport basis232+
- [Message context elaboration](#improve-context-elaboration)233+
- Message transportation234+
- [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 cycle149239
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 elaboration249+
250+
#### Presentation159251
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 elaboration287+
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+
```ts293+
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: ExtendedContext302+
) => {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+
### Transport327+
328+
#### Preparation195329
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+
#### Formatting221357
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 transportation395+
#### Transportation260396
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 formatting266-
267-
### Improve context elaboration268-
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-
```ts274-
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: ExtendedContext283-
) => {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-
```assets/colorized.pngrenamedView file
Loading diff…