@infineit/winston-logger 1.0.33 → 1.0.35

package/README.md

@@ -53,23 +53,20 @@ This package requires the following peer dependencies (usually already installed
 
 ### ⚠️ Critical Setup Requirement
 
-**IMPORTANT:** `ClsModule.forRoot()` **MUST** be imported in your `AppModule` **BEFORE** `ContextModule`. This is required to avoid dependency resolution errors with `HttpAdapterHost`.
+**IMPORTANT:** `ContextModule` internally imports and exports `ClsModule.forRoot()` with `mount: true` and `generateId: true`. **Applications MUST NOT import `ClsModule` separately** - just import `ContextModule`.
 
-**Correct import order:**
+**Correct import:**
 ```typescript
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
-    ClsModule.forRoot({ ... }),  // ✅ FIRST - Required
-    ContextModule,                // ✅ THEN - Uses existing ClsModule
-    LoggerModule.forRoot(),       // ✅ THEN - Configures logger
+    ContextModule,          // ✅ Includes ClsModule internally
+    LoggerModule.forRoot(), // ✅ Then configure logger
   ],
 })
 ```
 
-**❌ Incorrect:** Importing `ContextModule` before `ClsModule` will cause `HttpAdapterHost` dependency errors.
-
-**Note:** `ContextModule` does NOT import `ClsModule` internally. Applications must configure `ClsModule.forRoot()` themselves.
+**❌ Incorrect:** Do NOT import `ClsModule.forRoot()` in your `AppModule`. `ContextModule` handles it internally.
 
 ---
 
@@ -80,26 +77,12 @@ This package requires the following peer dependencies (usually already installed
 ```typescript
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
-import { ClsModule } from 'nestjs-cls';  // REQUIRED: Must import ClsModule first
-import { v4 as uuidv4 } from 'uuid';      // REQUIRED: For correlation ID generation
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
-    
-    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,  // Enable middleware for HTTP requests
-        generateId: true,  // Auto-generate correlation ID
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    
-    ContextModule,  // Required for CLS (correlation ID support) - uses existing ClsModule
+    ContextModule,  // Includes ClsModule internally with mount: true and generateId: true
     LoggerModule.forRoot(),  // Configure logger
   ],
 })
@@ -216,22 +199,9 @@ const config: LoggerModuleConfig = {
   // kafkaTopic: 'project-logs',      // Kafka topic (required if transportType='kafka')
 };
 
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
-
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule
+    ContextModule,  // Includes ClsModule internally
     LoggerModule.forRoot(config),
   ],
 })
@@ -282,26 +252,13 @@ export default registerAs('logger', () => ({
 ```
 
 ```typescript
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
-
 @Module({
   imports: [
     ConfigModule.forRoot({
       isGlobal: true,
       load: [loggerConfig],
     }),
-    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule configuration
+    ContextModule,  // Includes ClsModule internally
     LoggerModule.forRoot(),  // Will read from ConfigService
   ],
 })
@@ -397,26 +354,14 @@ export class UserController {
 }
 ```
 
-**Important**: For HTTP services, you must configure CLS middleware manually. **ClsModule MUST be imported BEFORE ContextModule:**
+**Important**: For HTTP services, `ContextModule` automatically configures CLS middleware with `mount: true` and `generateId: true`. Correlation IDs are handled automatically.
 
 ```typescript
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,  // Enable middleware
-        generateId: true,  // Auto-generate correlation ID
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Provides CLS service - uses existing ClsModule
+    ContextModule,  // Includes ClsModule internally with mount: true and generateId: true
     LoggerModule.forRoot(),
   ],
 })
@@ -610,8 +555,6 @@ export class KafkaTransport implements LoggerTransport {
 
 ```typescript
 import { Provider, Module } from '@nestjs/common';
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 import { KafkaTransport } from './kafka-transport';
 
@@ -624,17 +567,7 @@ const customTransports: Provider[] = [
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule
+    ContextModule,  // Includes ClsModule internally
     LoggerModule.forRoot(config, customTransports),
   ],
 })
@@ -679,23 +612,11 @@ LOGGER_HTTP_ENDPOINT=https://logging-service.example.com/api/logs
 
 **Via Module Configuration:**
 ```typescript
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule
+    ContextModule,  // Includes ClsModule internally
     LoggerModule.forRoot({
       // ... existing config
       forwardToCentral: true,
@@ -843,7 +764,7 @@ LOGGER_KAFKA_TOPIC=project-logs-common
 5. Check console errors: Forwarding errors are logged to `console.error` with message `"CentralLogForwarder forward error (swallowed): <error>"`
 
 **Correlation ID Missing:**
-- Ensure CLS is configured: `ClsModule.forRoot()` with `generateId: true`
+- Ensure `ContextModule` is imported: `ContextModule` automatically configures `ClsModule` with `generateId: true`
 - Ensure `ContextModule` is imported
 - Check that original logs have `correlationId` field (if not, forwarded logs won't either)
 
@@ -972,35 +893,21 @@ Correlation ID is **optional** - `undefined` is valid:
 
 ### HTTP Context Setup
 
-For HTTP services, configure CLS middleware. **ClsModule MUST be imported BEFORE ContextModule:**
+For HTTP services, `ContextModule` automatically configures CLS middleware. No additional setup required:
 
 ```typescript
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => {
-          // Use existing correlation ID from header, or generate new one
-          return (req.headers['x-correlation-id'] as string) || uuidv4();
-        },
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule configuration
+    ContextModule,  // Automatically configures ClsModule with mount: true and generateId: true
     LoggerModule.forRoot(),
   ],
 })
 export class AppModule {}
 ```
 
-**Important:** The import order is critical. `ClsModule.forRoot()` must be imported before `ContextModule` to avoid `HttpAdapterHost` dependency resolution errors.
+**Important:** `ContextModule` internally handles `ClsModule` configuration. Do NOT import `ClsModule` separately in your `AppModule`.
 
 ### CLS Context Boundaries and Edge Cases
 
@@ -1170,30 +1077,7 @@ if (correlationId && validateCorrelationId(correlationId)) {
 
 #### Validation in HTTP Middleware
 
-```typescript
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
-
-// ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule in AppModule
-ClsModule.forRoot({
-  global: true,
-  middleware: {
-    mount: true,
-    generateId: true,
-    idGenerator: (req: Request) => {
-      const headerId = req.headers['x-correlation-id'] as string;
-      
-      // Validate format
-      if (headerId && uuidValidate(headerId)) {
-        return headerId;
-      }
-      
-      // Generate new one if invalid
-      return uuidv4();
-    },
-  },
-})
-```
+**Note:** `ContextModule` automatically configures `ClsModule` with `mount: true` and `generateId: true`. Correlation IDs are automatically generated. If you need custom validation, you can access `ClsService` directly (exported by `ContextModule`) or use `ContextStorageService.setContextId()` in your middleware.
 
 #### Validation in Kafka Consumers
 
@@ -1224,26 +1108,12 @@ async handleOrderCreated(message: OrderCreatedEvent) {
 ```typescript
 import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4, validate as uuidValidate } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
-    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => {
-          const headerId = req.headers['x-correlation-id'] as string;
-          return (headerId && uuidValidate(headerId)) ? headerId : uuidv4();
-        },
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule configuration
+    ContextModule,  // Includes ClsModule internally with mount: true and generateId: true
     LoggerModule.forRoot({
       nodeEnv: process.env.NODE_ENV,
       organization: 'sales',
@@ -1255,7 +1125,7 @@ import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
     // Additional middleware can be added here
-    // ClsModule middleware is already mounted above
+    // ContextModule already configures ClsModule middleware internally
   }
 }
 ```
@@ -1679,25 +1549,11 @@ async createInvoice(@Body() data: CreateInvoiceDto, @Headers() headers: Headers)
 **4. Common Service (app.module.ts):**
 
 ```typescript
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => {
-          // Extract from header (propagated from Document Service)
-          return (req.headers['x-correlation-id'] as string) || uuidv4();
-        },
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule configuration
+    ContextModule,  // Includes ClsModule internally with mount: true and generateId: true
     LoggerModule.forRoot(),
   ],
 })
@@ -1862,23 +1718,11 @@ bootstrap();
 ```typescript
 // ✅ CORRECT: Use LoggerService injection
 import { NestFactory } from '@nestjs/core';
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported BEFORE ContextModule
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule
+    ContextModule,  // ✅ Includes ClsModule internally with mount: true and generateId: true
     LoggerModule.forRoot(),
   ],
 })
@@ -1982,15 +1826,11 @@ export class MyService {
    this.logger.info('message');
    ```
 
-5. **Configure CLS middleware (for HTTP services)**
+5. **Import ContextModule (automatically configures CLS middleware)**
    ```typescript
-   // ✅ Add CLS middleware configuration
-   ClsModule.forRoot({
-     middleware: {
-       mount: true,
-       generateId: true,
-     },
-   }),
+   // ✅ ContextModule automatically configures ClsModule with mount: true and generateId: true
+   // No need to import ClsModule separately
+   ContextModule,
    ```
 
 ### Reassurance: Nothing Breaks
@@ -2036,24 +1876,12 @@ async function bootstrap() {
 **After (Current)**:
 ```typescript
 import { NestFactory } from '@nestjs/core';
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
-    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
-    ClsModule.forRoot({
-      global: true,
-      middleware: { 
-        mount: true, 
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // ✅ Uses existing ClsModule
-    LoggerModule.forRoot(),  // ✅ Add
+    ContextModule,  // ✅ Includes ClsModule internally with mount: true and generateId: true
+    LoggerModule.forRoot(),  // ✅ Configure logger
   ],
 })
 export class AppModule {}
@@ -2070,9 +1898,10 @@ async function bootstrap() {
 
 If you encounter issues during migration:
 
-1. **Check module imports**: Ensure `ClsModule.forRoot()` is imported **BEFORE** `ContextModule`, then `LoggerModule.forRoot()` in your `AppModule`
-2. **Check CLS setup**: For HTTP services, ensure `ClsModule.forRoot()` is configured with `middleware: { mount: true, generateId: true }`
-3. **Check import order**: `ClsModule` must come before `ContextModule` to avoid `HttpAdapterHost` dependency errors
+1. **Check module imports**: Ensure `ContextModule` and `LoggerModule.forRoot()` are in your `AppModule`
+2. **Do NOT import ClsModule**: `ContextModule` handles `ClsModule` internally - do NOT import it separately
+3. **Check injection**: Ensure `LoggerService` is injected via constructor
+4. **Review examples**: See the "Usage in Different Contexts" section above
 4. **Check injection**: Ensure `LoggerService` is injected via constructor
 5. **Review examples**: See the "Usage in Different Contexts" section above
 
@@ -2235,24 +2064,12 @@ async log(...) {  // ❌
 ```typescript
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
-import { ClsModule } from 'nestjs-cls';
-import { v4 as uuidv4 } from 'uuid';
 import { ContextModule, LoggerModule } from '@infineit/winston-logger';
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
-    // ⚠️ CRITICAL: ClsModule MUST be imported FIRST
-    ClsModule.forRoot({
-      global: true,
-      middleware: {
-        mount: true,
-        generateId: true,
-        idGenerator: (req: Request) => 
-          (req.headers['x-correlation-id'] as string) || uuidv4(),
-      },
-    }),
-    ContextModule,  // Uses existing ClsModule configuration
+    ContextModule,  // Includes ClsModule internally with mount: true and generateId: true
     LoggerModule.forRoot({
       nodeEnv: process.env.NODE_ENV,
       organization: 'my-org',

package/context/infrastructure/nestjs/contextModule.js

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextModule = void 0;
 const common_1 = require("@nestjs/common");
+const nestjs_cls_1 = require("nestjs-cls");
 const contextStorageService_1 = require("../../../context/domain/interfaces/contextStorageService");
 const nestjsClsContextStorageService_1 = __importDefault(require("../../../context/infrastructure/nestjs-cls/nestjsClsContextStorageService"));
 let ContextModule = class ContextModule {
@@ -19,7 +20,15 @@ exports.ContextModule = ContextModule;
 exports.ContextModule = ContextModule = __decorate([
     (0, common_1.Global)(),
     (0, common_1.Module)({
-        imports: [],
+        imports: [
+            nestjs_cls_1.ClsModule.forRoot({
+                global: true,
+                middleware: {
+                    mount: false,
+                    generateId: false,
+                },
+            }),
+        ],
         controllers: [],
         providers: [
             {
@@ -27,7 +36,7 @@ exports.ContextModule = ContextModule = __decorate([
                 useClass: nestjsClsContextStorageService_1.default,
             },
         ],
-        exports: [contextStorageService_1.ContextStorageServiceKey],
+        exports: [contextStorageService_1.ContextStorageServiceKey, nestjs_cls_1.ClsModule],
     })
 ], ContextModule);
 //# sourceMappingURL=contextModule.js.map

package/context/infrastructure/nestjs/contextModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"contextModule.js","sourceRoot":"","sources":["../../../../../libs/src/context/infrastructure/nestjs/contextModule.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAgD;AAIhD,oGAAoG;AACpG,+IAAuH;AA2ChH,IAAM,aAAa,GAAnB,MAAM,aAAa;CAAG,CAAA;AAAhB,sCAAa;wBAAb,aAAa;IAhBzB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACJ,OAAO,EAAE,EAIR;QACD,WAAW,EAAE,EAAE;QACf,SAAS,EAAE;YACP;gBACI,OAAO,EAAE,gDAAwB;gBACjC,QAAQ,EAAE,wCAA8B;aAC3C;SACJ;QACD,OAAO,EAAE,CAAC,gDAAwB,CAAC;KACtC,CAAC;GACW,aAAa,CAAG"}
+{"version":3,"file":"contextModule.js","sourceRoot":"","sources":["../../../../../libs/src/context/infrastructure/nestjs/contextModule.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAgD;AAEhD,2CAAuC;AAEvC,oGAAoG;AACpG,+IAAuH;AAuDhH,IAAM,aAAa,GAAnB,MAAM,aAAa;CAAG,CAAA;AAAhB,sCAAa;wBAAb,aAAa;IAvBzB,IAAA,eAAM,GAAE;IACR,IAAA,eAAM,EAAC;QACJ,OAAO,EAAE;YAIL,sBAAS,CAAC,OAAO,CAAC;gBACd,MAAM,EAAE,IAAI;gBACZ,UAAU,EAAE;oBACR,KAAK,EAAE,KAAK;oBACZ,UAAU,EAAE,KAAK;iBACpB;aACJ,CAAC;SACL;QACD,WAAW,EAAE,EAAE;QACf,SAAS,EAAE;YACP;gBACI,OAAO,EAAE,gDAAwB;gBACjC,QAAQ,EAAE,wCAA8B;aAC3C;SACJ;QACD,OAAO,EAAE,CAAC,gDAAwB,EAAE,sBAAS,CAAC;KACjD,CAAC;GACW,aAAa,CAAG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infineit/winston-logger",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "Enterprise-level logger integration package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",