From ec9ddba66990795a4274415f78f67ac7250c86ec Mon Sep 17 00:00:00 2001 From: Eugene Terehov Date: Tue, 15 Nov 2022 18:31:42 +0200 Subject: [PATCH] Update readme with some backwards compatibility docs --- README.md | 28 +++++++++++++++++++++++++--- docs/README.md | 38 ++++++++++++++++++++++++++++++-------- examples/nodejs/index2.ts | 4 ++++ 3 files changed, 59 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 6fed0c9..1584479 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Node.js with JavaScript: node --enable-source-maps ``` -Node.js with TypeScript (with ESM support): +Node.js with TypeScript and `ts-node` (with ESM support): ```bash node --enable-source-maps --experimental-specifier-resolution=node --no-warnings --loader ts-node/esm ``` @@ -140,6 +140,9 @@ logger.fatal(new Error("I am a pretty Error with a stacktrace.")); ## API documentation +> **`tslog >= v4` is a major rewrite and introduces breaking changes.**
+> Please, follow this documentation when migrating. + ### Lifecycle of a log message Every incoming log message runs through a number of steps before being displayed or handed over to a "transport". Every step can be overwritten and adjusted. @@ -162,7 +165,7 @@ Every incoming log message runs through a number of steps before being displayed ```typescript import { Logger } from "tslog"; -const log: Logger = new Logger(); +const log = new Logger(); log.silly("I am a silly log."); log.trace("I am a trace log."); log.debug("I am a debug log."); @@ -547,8 +550,27 @@ const logMsg = logger.info("Test"); //} ``` +## Backwards compatibility + +> **`tslog` follows a semantic release policy.** A major version change indicates breaking changes.

+> `tslog >=4` is less limiting when it comes to configuration. There are many use cases (especially when it comes to integration with 3rd party services) that now can be achieved elegantly and were not possible before. + +### Name and other constructor parameters + +`tslog` < 4 had a name parameter on the constructor. v4 removed all preconfigured parameters and allows you to create your own log object (s. "Defining and accessing `logObj`"). + +**OLD:** `tslog` < 4 +```typescript +const log: Logger = new Logger({ name: "myLogger" }); +``` + +**NEW:** `tslog` >= 4 +```typescript +const log = new Logger({ type: "json" }, { name: "DefaultLogger" }); +``` + -### Tip: RequestID: Mark a request (e.g. HTTP) call with AsyncLocalStorage and `tslog` +### RequestID: Mark a request (e.g. HTTP) call with AsyncLocalStorage and `tslog` >**Node.js 13.10 introduced a new feature called AsyncLocalStorage.**
**❗ Keep track of all subsequent calls and promises originated from a single request (e.g. HTTP).** diff --git a/docs/README.md b/docs/README.md index 5a1d0d8..1584479 100644 --- a/docs/README.md +++ b/docs/README.md @@ -77,7 +77,7 @@ Node.js with JavaScript: node --enable-source-maps ``` -Node.js with TypeScript (with ESM support): +Node.js with TypeScript and `ts-node` (with ESM support): ```bash node --enable-source-maps --experimental-specifier-resolution=node --no-warnings --loader ts-node/esm ``` @@ -108,7 +108,7 @@ Browser: ```typescript import { Logger } from "tslog"; -const logger = new Logger({ name: "myLogger" }); +const logger = new Logger(); logger.silly("I am a silly log."); logger.trace("I am a trace log."); logger.debug("I am a debug log."); @@ -140,6 +140,9 @@ logger.fatal(new Error("I am a pretty Error with a stacktrace.")); ## API documentation +> **`tslog >= v4` is a major rewrite and introduces breaking changes.**
+> Please, follow this documentation when migrating. + ### Lifecycle of a log message Every incoming log message runs through a number of steps before being displayed or handed over to a "transport". Every step can be overwritten and adjusted. @@ -148,7 +151,7 @@ Every incoming log message runs through a number of steps before being displayed - **log message** Log message comes in through the `BaseLogger.log()` method - **mask** If masking is configured, log message gets recursively masked -- **toLogObj** Log message gets transformed into a log object: A default typed log object can be passed to constructor as a second parameter and will be cloned and enriched with the incoming log parameters. Error properties will be handled accordingly. If there is only one log property, and it's an object, both objects (cloned default `logObj` as well as the log property object will be merged.) If there are more than one, they will be put into properties called "0", "1", ... and so on. Alternatively, log message properties can be put into a property with a name configured with the `argumentsArrayName` setting. +- **toLogObj** Log message gets transformed into a log object: A default typed log object can be passed to constructor as a second parameter and will be cloned and enriched with the incoming log parameters. Error properties will be handled accordingly. If there is only one log property, and it's an object, both objects (cloned default `logObj` as well as the log property object) will be merged. If there are more than one, they will be put into properties called "0", "1", ... and so on. Alternatively, log message properties can be put into a property with a name configured with the `argumentsArrayName` setting. - **addMetaToLogObj** Additional meta information, like the source code position of the log will be gathered and added to the `_meta` property or any other one configured with the setting `metaProperty`. - **format** In case of "pretty" configuration, a log object will be formatted based on the templates configured in settings. Meta will be formatted by the method `_prettyFormatLogObjMeta` and the actual log payload will be formatted by `prettyFormatLogObj`. Both steps can be overwritten with the settings `formatMeta` and `formatMeta`. - **transport** Last step is to "transport" a log message to every attached transport from the setting `attachedTransports`. Last step is the actual transport, either JSON (`transportJSON`), formatted (`transportFormatted`) or omitted, if its set to "hidden". Both default transports can also be overwritten by the corresponding setting. @@ -157,12 +160,12 @@ Every incoming log message runs through a number of steps before being displayed `tslog` comes with default log level `0: silly`, `1: trace`, `2: debug`, `3: info`, `4: warn`, `5: error`, `6: fatal`. -> **Tip:** Each logging method has a return type, which is a _JSON_ representation of the log message (`ILogObject`). +> **Tip:** Each logging method has a return type, which is a _JSON_ representation of the log message (`ILogObj`). ```typescript import { Logger } from "tslog"; -const log: Logger = new Logger(); +const log = new Logger(); log.silly("I am a silly log."); log.trace("I am a trace log."); log.debug("I am a debug log."); @@ -477,7 +480,7 @@ For every log: }); ``` -For `pretty` logs log: +For `pretty` logs: ```typescript const logger = new Logger({ type: "pretty", @@ -495,7 +498,7 @@ For `pretty` logs log: }); ``` -For `JSON` logs log (no formatting happens here): +For `JSON` logs (no formatting happens here): ```typescript const logger = new Logger({ type: "pretty", @@ -547,8 +550,27 @@ const logMsg = logger.info("Test"); //} ``` +## Backwards compatibility + +> **`tslog` follows a semantic release policy.** A major version change indicates breaking changes.

+> `tslog >=4` is less limiting when it comes to configuration. There are many use cases (especially when it comes to integration with 3rd party services) that now can be achieved elegantly and were not possible before. + +### Name and other constructor parameters + +`tslog` < 4 had a name parameter on the constructor. v4 removed all preconfigured parameters and allows you to create your own log object (s. "Defining and accessing `logObj`"). + +**OLD:** `tslog` < 4 +```typescript +const log: Logger = new Logger({ name: "myLogger" }); +``` + +**NEW:** `tslog` >= 4 +```typescript +const log = new Logger({ type: "json" }, { name: "DefaultLogger" }); +``` + -### Tip: RequestID: Mark a request (e.g. HTTP) call with AsyncLocalStorage and `tslog` +### RequestID: Mark a request (e.g. HTTP) call with AsyncLocalStorage and `tslog` >**Node.js 13.10 introduced a new feature called AsyncLocalStorage.**
**❗ Keep track of all subsequent calls and promises originated from a single request (e.g. HTTP).** diff --git a/examples/nodejs/index2.ts b/examples/nodejs/index2.ts index 4b5d98a..e22b1aa 100644 --- a/examples/nodejs/index2.ts +++ b/examples/nodejs/index2.ts @@ -46,3 +46,7 @@ jsonLoggerArgumentsArray.silly("test"); jsonLoggerArgumentsArray.silly("test1", "test2"); //////////////////////////// + +const log = new Logger({ type: "json" }, { name: "DefaultLogger" }); + +log.silly("foo bar");