Update readme with some backwards compatibility docs

Author: terehov

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.** <br> 
+> Please, follow this documentation when migrating. 
+
 ### <a name="life_cycle"></a>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.<br><br>
+> `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 <a href="https://nodejs.org/api/async_hooks.html#async_hooks_class_asynclocalstorage" target="_blank">AsyncLocalStorage.</a>**<br>
 
 **❗ Keep track of all subsequent calls and promises originated from a single request (e.g. HTTP).**

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.** <br> 
+> Please, follow this documentation when migrating. 
+
 ### <a name="life_cycle"></a>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.<br><br>
+> `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 <a href="https://nodejs.org/api/async_hooks.html#async_hooks_class_asynclocalstorage" target="_blank">AsyncLocalStorage.</a>**<br>
 
 **❗ Keep track of all subsequent calls and promises originated from a single request (e.g. HTTP).**

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");