Merge pull request #17 from Wiredcraft/feat-document-transform-features

feat: document transformers feature

.gitignore

@@ -36,4 +36,6 @@ lerna-debug.log*
 !.vscode/extensions.json
 
 # Temp files
-*.temp
+*.temp
+
+.vscode

README.md

@@ -4,19 +4,21 @@ A logger module for [Nestjs](https://github.com/nestjs/nest), built on top of [n
 
 # Features
 
-* A gloabl bunyan logger provider can be used in the controllers/services.
-* Automatically log request/response with `request-id`, `timestamp`, `status-code`, etc.
+- A gloabl bunyan logger provider can be used in the controllers/services.
+- Automatically log request/response with `request-id`, `timestamp`, `status-code`, etc.
 
 # Usage
 
 ## Installation
 
 ### Yarn
+
 ```
 yarn add @wiredcraft/nestjs-bunyan-logger
 ```
 
 ### NPM
+
 ```
 npm install @wiredcraft/nestjs-bunyan-logger --save
 ```
@@ -48,34 +50,203 @@ export class AppModule {}
 ```
 
 A sample configuration file is as below,
+
 ```typescript
 export default () => ({
   logger: {
-      name: 'awesome-app',
-      streamType: 'FILE' | 'STDOUT',
-      path: './logs/app.log', // only available for `FILE` streamType
-      excludeReqPath: '/health', // the path that you want to skip logging
-  }
+    name: 'awesome-app',
+    streamType: 'FILE' | 'STDOUT',
+    path: './logs/app.log', // only available for `FILE` streamType
+    excludeReqPath: '/health', // the path that you want to skip logging
+  },
 });
-
 ```
 
-
 2. Inject the logger instance to your service and use it as you want.
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { Logger, Bunyan  } from '@wiredcraf/nestjs-bunyan-logger';
+import { Logger, Bunyan } from '@wiredcraf/nestjs-bunyan-logger';
 
 @Injectable()
 export class CatService {
-  constructor(
-    @Logger() private logger: Bunyan,
-  ) {
-  }
+  constructor(@Logger() private logger: Bunyan) {}
 }
 ```
 
+## Transformers Option
+
+![image](./docs/images/transformers-workflow.png)
+
+`transformers` is a config option that could allow the user to specify a list of customized transform rules to apply to each log entry. The current library supports three types of transformers: `constant`, `clone` and `map`.
+
+### Constant
+
+`constant` type allows the user to copy a **object type** constant directly to the log entry. An example is as follows:
+
+```js
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers: [{ constant: { customField: '123' } }],
+};
+
+logger.info({ originalField: 'abc' });
+
+// The above will generate the following log entry:
+//  {
+//    originalField: 'abc',
+//    customField: '123'
+//  }
+```
+
+### Clone
+
+`clone` type allows the user to copy value from one fieldname to the specified fieldname with the following rules:
+
+- The original field is not removed from the log entry
+- Only one embed level is allowed in new Fieldname specification
+
+An example is as follows:
+
+```js
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers: [{ clone: { originalField: 'newField' } }],
+};
+
+logger.info({ originalField: 'abc' });
+
+// The above will generate the following log entry:
+//  {
+//    originalField: 'abc',
+//    newField: 'abc'
+//  }
+```
+
+An one embed level example is as follows:
+
+```js
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers: [{ clone: { originalField: 'newParent.newField' } }],
+};
+
+logger.info({ originalField: 'abc' });
+
+// The above will generate the following log entry:
+//  {
+//    originalField: 'abc',
+//    newParent: {
+//      {
+//        newField: 'abc'
+//      }
+//    }
+//  }
+```
+
+### Map
+
+`map` type allows the user to apply a map value or a map function to the target field and replace the field value with the mapped value with the following rules:
+
+- only one embed level is allowed for original field name specification
+
+An example of simple map value is as follows:
+
+```js
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers: [{ map: { originalField: 'new-value' } }],
+};
+
+logger.info({ originalField: 'abc' });
+
+// The above will generate the following log entry:
+//  {
+//    originalField: 'new-value',
+//  }
+```
+
+An example of map function is as follows:
+
+```js
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers: [
+    { map: { originalField: (oldValue) => oldValue + 'transformed' } },
+  ],
+};
+
+logger.info({ originalField: 'abc' });
+
+// The above will generate the following log entry:
+//  {
+//    originalField: 'abctransformed',
+//  }
+```
+
+An one embed level example is as follows:
+
+```js
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers: [
+    { map: { ['originalParentField.originalField']: 'new-value' } },
+  ],
+};
+
+logger.info({
+  originalParentField: {
+    originalField: 'abc',
+  },
+});
+
+// The above will generate the following log entry:
+// {
+//   originalParentField: {
+//    originalField: 'new-value',
+//   },
+// }
+```
+
+### Multiple transformers
+
+Multiple transformers are applied in the order as they are specified in the `transformers` option. An example is as follows:
+
+```js
+const transformers = [
+  {
+    constant: { customField: 'custom-value' },
+  },
+  {
+    clone: { originalField: 'backupField' },
+  },
+  {
+    map: { originalField: (oldValue) => oldValue + 'transformed' },
+  },
+];
+
+const options: LoggerConfig = {
+  name: 'test-app',
+  streamType: 'STDOUT',
+  transformers,
+};
+
+logger.info({ originalField: 'original-value' });
+
+// The above will generate the following log entry:
+// {
+//   originalField: 'original-value-transformed',
+//   backupField: 'original-value',
+//   customField: 'custom-value'
+// }
+```
+
 # Development
 
 ## Installation
@@ -86,7 +257,7 @@ $ yarn install
 
 ## Publish
 
-``` bash
+```bash
 $ npm version major|minor|patch
 $ npm publish
 ```

src/logger.providers.ts

@@ -1,6 +1,6 @@
 import { Provider } from '@nestjs/common';
 import { APP_INTERCEPTOR } from '@nestjs/core';
-import * as Bunyan from 'bunyan';
+import Bunyan from 'bunyan';
 
 import { LOGGER, LOGGER_OPTIONS } from './constants';
 import { RequestInterceptor } from './logger.interceptor';