doc: update the documentation for WithContext to prevent bugs (#18)

Author: itaywol

README.md

@@ -461,21 +461,21 @@ export class NestedService {
 
 **Message Handlers**: Add service identification and correlation tracking
 ```typescript
-@WithContext(() => ({ correlationId: uuid(), handler: 'user.validate' }))
 @MessagePattern('user.validate')
+@WithContext(() => ({ correlationId: uuid(), handler: 'user.validate' }))
 async validateUser(@Payload() data: ValidateUserDto) {
   this.logger.log('Validating user credentials');
 }
 ```
 
 **Cron Jobs**: Track scheduled task execution
 ```typescript
+@Cron('0 2 * * *')
 @WithContext(() => ({ 
   task: 'data-sync',
   executionId: uuid(),
   scheduledAt: new Date().toISOString()
 }))
-@Cron('0 2 * * *')
 async syncUserData() {
   this.logger.log('Starting user data synchronization');
 }
@@ -489,6 +489,28 @@ async processEmailBatch(emails: Email[]) {
 }
 ```
 
+### Decorator Positioning
+
+**⚠️ IMPORTANT**: When using `@WithContext`, it **must be placed closer to the function definition** than other decorators to ensure proper context initialization.
+
+```typescript
+// ✅ Correct - @WithContext closer to function
+@MessagePattern('user.created')
+@WithContext(() => ({ correlationId: uuid() }))
+async handleUserCreated(data: CreateUserDto) {
+  this.logger.log('Processing user creation');
+}
+
+// ❌ Incorrect - @WithContext too far from function
+@WithContext(() => ({ correlationId: uuid() }))
+@MessagePattern('user.created')
+async handleUserCreated(data: CreateUserDto) {
+  this.logger.log('Processing user creation'); // Context may not be available
+}
+```
+
+This applies to all NestJS decorators including `@MessagePattern`, `@EventPattern`, `@Cron`, etc.
+
 ### When to Use @WithContext vs updateContext()
 
 **Use `@WithContext` for:**
@@ -545,6 +567,23 @@ async processEmailBatch(emails: Email[]) {
    logger.info('Item fetched id: 1, time: 2000, source: serviceA');
    ```
 
+4. **Position @WithContext Correctly**
+   ```typescript
+   // ✅ Good - @WithContext farther from function
+   @MessagePattern('user.created')
+   @WithContext(() => ({ correlationId: uuid() }))
+   async handleUserCreated(data: CreateUserDto) {
+     this.logger.log('Processing user creation');
+   }
+
+   // ❌ Not good - @WithContext too close to function
+   @WithContext(() => ({ correlationId: uuid() }))
+   @MessagePattern('user.created')
+   async handleUserCreated(data: CreateUserDto) {
+     this.logger.log('Processing user creation');
+   }
+   ```
+
 # Performance Considerations
 
 This logger uses `AsyncLocalStorage` to maintain context, which does add an overhead.

src/decorators/with-context.decorator.ts

@@ -7,20 +7,20 @@ import { ContextStore } from '../store/context-store';
  *
  * @example
  * ```typescript
- * @WithContext()
  * @MessagePattern('user.created')
+ * @WithContext()
  * async handleUserCreated(data: CreateUserDto) {
  *   this.logger.log('Processing user creation');
  * }
  *
- * @WithContext({ userId: 'user_123' })
  * @Cron('0 0 * * *')
+ * @WithContext({ userId: 'user_123' })
  * async dailyReport() {
  *   this.logger.log('Running daily report');
  * }
  *
- * @WithContext(() => ({ correlationId: uuid(), service: 'UserService' }))
  * @MessagePattern('user.validate')
+ * @WithContext(() => ({ correlationId: uuid(), service: 'UserService' }))
  * async validateUser(data: ValidateUserDto) {
  *   this.logger.log('Validating user'); // Fresh correlationId each call
  * }