@rolandsall24/nest-mediator 0.5.2 → 0.7.0

package/README.md

@@ -4,11 +4,13 @@ A lightweight CQRS (Command Query Responsibility Segregation) mediator pattern i
 
 ## Features
 
-- Clean separation between Commands and Queries
+- Clean separation between Commands, Queries, and Events
 - Type-safe handlers with TypeScript
 - Decorator-based handler registration
 - Automatic handler discovery and registration
-- **Pipeline Behaviors** for cross-cutting concerns (logging, validation, etc.)
+- Pipeline Behaviors for cross-cutting concerns (logging, validation, etc.)
+- Type-Specific Behaviors - behaviors that only apply to specific request types (v0.6.0+)
+- **Domain Events with Critical/Non-Critical consumers (v0.7.0+)**
 - Built-in behaviors: Logging, Validation, Exception Handling, Performance Tracking
 - Built on top of NestJS dependency injection
 - Zero runtime dependencies beyond NestJS
@@ -32,57 +34,80 @@ This library requires TypeScript decorators to be enabled. Add the following to
 }
 ```
 
-## Upgrading to v0.5.0
+## Upgrading to v0.7.0
 
-Version 0.5.0 introduces **Pipeline Behaviors** while maintaining backward compatibility. Existing code using `NestMediatorModule.forRoot()` will continue to work without changes.
+Version 0.7.0 introduces **Domain Events** with Critical and Non-Critical consumer support.
 
 ### What's New
 
-- Pipeline behaviors for cross-cutting concerns (logging, validation, etc.)
-- Built-in behaviors: `LoggingBehavior`, `ValidationBehavior`, `ExceptionHandlingBehavior`, `PerformanceBehavior`
-- New `forRoot()` method for enabling behaviors
-- Custom `HandlerNotFoundException` for better error handling
+- `IEvent` interface for domain events
+- `IEventConsumer<TEvent>` interface for event consumers
+- `ICriticalEventConsumer<TEvent>` interface for critical consumers with optional compensation
+- `@EventHandler(EventClass)` decorator to register consumers
+- `@Critical({ order: n })` decorator for critical consumers (run sequentially)
+- `@NonCritical()` decorator for non-critical consumers (fire-and-forget)
+- `mediatorBus.publish(event)` method to publish events
+- `EventCriticality` enum (`CRITICAL`, `NON_CRITICAL`)
+- **Saga-style compensation**: Critical consumers can define a `compensate()` method that runs in reverse order when a subsequent consumer fails
+- Internal architecture refactoring (MediatorBus now delegates to CommandBus, QueryBus, EventBus)
 
-### Breaking Change Notice
+### Backward Compatibility
 
-The `send()` and `query()` methods now throw `HandlerNotFoundException` instead of a generic `Error` when no handler is registered. This is **backward compatible** since `HandlerNotFoundException` extends `Error`, but you may want to update your error handling for more specific catches:
+- **`IEventHandler` renamed to `IEventConsumer`**: `IEventHandler` is now a deprecated type alias. Update your imports:
 
-```typescript
-// Before (still works)
-try {
-  await mediator.send(command);
-} catch (error) {
-  if (error instanceof Error) {
-    console.log(error.message); // Works as before
-  }
-}
+- **MediatorBus API unchanged**: The `send()`, `query()`, and `publish()` methods work exactly as before
+- **No breaking changes**: Existing command/query code continues to work without modifications
+
+---
+
+## Upgrading to v0.6.0
+
+Version 0.6.0 introduces **Type-Specific Pipeline Behaviors** - behaviors that only apply to specific request types.
+
+### What's New
+
+- New `@Handle()` decorator for the `handle` method to enable automatic request type inference
+- Behaviors can target specific command/query types without manual `instanceof` checks
+- Full backward compatibility - existing behaviors work unchanged
 
-// After (optional - for more specific handling)
-import { HandlerNotFoundException } from '@rolandsall24/nest-mediator';
+### Type-Specific Behavior Example
 
-try {
-  await mediator.send(command);
-} catch (error) {
-  if (error instanceof HandlerNotFoundException) {
-    console.log(`No handler for: ${error.requestName}`);
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IPipelineBehavior, PipelineBehavior, Handle } from '@rolandsall24/nest-mediator';
+import { CreateUserCommand } from './create-user.command';
+
+@Injectable()
+@PipelineBehavior({ priority: 100, scope: 'command' })
+export class CreateUserValidationBehavior
+  implements IPipelineBehavior<CreateUserCommand, void>
+{
+  @Handle()  // <-- Enables type inference from method signature
+  async handle(
+    request: CreateUserCommand,
+    next: () => Promise<void>,
+  ): Promise<void> {
+    // This behavior ONLY runs for CreateUserCommand
+    // No instanceof check needed!
+    if (!request.email.includes('@')) {
+      throw new Error('Invalid email');
+    }
+    return next();
   }
 }
 ```
 
-### No Migration Required
+### How It Works
 
-If you're using `NestMediatorModule.forRoot()`, no changes are needed. Pipeline behaviors are **opt-in** via `forRoot()`:
+1. Apply `@PipelineBehavior()` to the class and `@Handle()` to the `handle` method
+2. TypeScript's `emitDecoratorMetadata` emits type information for the method parameters
+3. The library reads this metadata at registration time and filters behaviors by request type
 
-```typescript
-// Existing code - works exactly as before (no behaviors)
-NestMediatorModule.forRoot()
+### No Migration Required
 
-// New - opt-in to behaviors
-NestMediatorModule.forRoot({
-  enableLogging: true,
-  enableValidation: true,
-})
-```
+Existing behaviors without `@Handle()` on the method continue to work exactly as before - they apply to all requests matching their scope.
+
+---
 
 ## Quick Start
 
@@ -287,6 +312,236 @@ export class UserController {
 }
 ```
 
+### Domain Events
+
+Domain events notify other parts of the system when something important happens. They support two consumer types:
+
+- **Critical consumers**: Run sequentially in order. Must succeed for the operation to complete.
+- **Non-critical consumers**: Run in parallel after critical consumers complete. Fire-and-forget.
+
+#### 1. Define an Event
+
+```typescript
+import { IEvent } from '@rolandsall24/nest-mediator';
+
+export class OrderPlacedEvent implements IEvent {
+  constructor(
+    public readonly orderId: string,
+    public readonly customerId: string,
+    public readonly items: { productId: string; quantity: number }[],
+    public readonly total: number,
+  ) {}
+}
+```
+
+#### 2. Create Event Consumers
+
+**Critical consumer** (must succeed, runs in order):
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+import { EventHandler, IEventConsumer, Critical } from '@rolandsall24/nest-mediator';
+import { OrderPlacedEvent } from './order-placed.event';
+
+@Injectable()
+@EventHandler(OrderPlacedEvent)
+@Critical({ order: 1 })  // Runs first among critical consumers
+export class ValidateInventoryConsumer implements IEventConsumer<OrderPlacedEvent> {
+  private readonly logger = new Logger(ValidateInventoryConsumer.name);
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    this.logger.log(`Validating inventory for order ${event.orderId}`);
+    // Validate all items are in stock
+    // Throw error if validation fails - stops the event processing
+  }
+}
+```
+
+**Critical consumer with compensation** (implements rollback on failure):
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+import { EventHandler, ICriticalEventConsumer, Critical } from '@rolandsall24/nest-mediator';
+import { OrderPlacedEvent } from './order-placed.event';
+
+@Injectable()
+@EventHandler(OrderPlacedEvent)
+@Critical({ order: 2 })
+export class ReserveInventoryConsumer implements ICriticalEventConsumer<OrderPlacedEvent> {
+  private readonly logger = new Logger(ReserveInventoryConsumer.name);
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    this.logger.log(`Reserving inventory for order ${event.orderId}`);
+    // Reserve inventory in the database
+  }
+
+  // Called if a SUBSEQUENT critical consumer fails (e.g., ChargePayment at order 4)
+  async compensate(event: OrderPlacedEvent): Promise<void> {
+    this.logger.warn(`[COMPENSATE] Releasing inventory for order ${event.orderId}`);
+    // Release the reserved inventory
+  }
+}
+```
+
+**Non-critical consumer** (fire-and-forget):
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+import { EventHandler, IEventConsumer, NonCritical } from '@rolandsall24/nest-mediator';
+import { OrderPlacedEvent } from './order-placed.event';
+
+@Injectable()
+@EventHandler(OrderPlacedEvent)
+@NonCritical()  // Runs in background after critical consumers
+export class SendOrderConfirmationConsumer implements IEventConsumer<OrderPlacedEvent> {
+  private readonly logger = new Logger(SendOrderConfirmationConsumer.name);
+
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    this.logger.log(`Sending confirmation email for order ${event.orderId}`);
+    // Send email - failures are logged but don't affect the order
+  }
+}
+
+// Consumers without @Critical or @NonCritical default to non-critical
+@Injectable()
+@EventHandler(OrderPlacedEvent)
+export class TrackAnalyticsConsumer implements IEventConsumer<OrderPlacedEvent> {
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    // Track analytics - non-critical by default
+  }
+}
+```
+
+#### 3. Publish Events from Command Handlers
+
+The recommended pattern is to publish domain events from command handlers after the main operation succeeds:
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+import { CommandHandler, ICommandHandler, MediatorBus } from '@rolandsall24/nest-mediator';
+import { PlaceOrderCommand } from './place-order.command';
+import { OrderPlacedEvent } from '../events/order-placed.event';
+
+@Injectable()
+@CommandHandler(PlaceOrderCommand)
+export class PlaceOrderHandler implements ICommandHandler<PlaceOrderCommand> {
+  private readonly logger = new Logger(PlaceOrderHandler.name);
+
+  constructor(private readonly mediatorBus: MediatorBus) {}
+
+  async execute(command: PlaceOrderCommand): Promise<void> {
+    const orderId = `order-${Date.now()}`;
+
+    // 1. Process the order (validate, save to DB, etc.)
+    this.logger.log(`Processing order ${orderId}`);
+    await this.processOrder(orderId, command);
+
+    // 2. Publish domain event after successful processing
+    // Critical consumers run sequentially, non-critical run in background
+    const result = await this.mediatorBus.publish(
+      new OrderPlacedEvent(
+        orderId,
+        command.customerId,
+        command.items,
+        command.total,
+      ),
+    );
+
+    this.logger.log(
+      `Order ${orderId} completed. Critical: ${result.criticalSucceeded}, Non-critical dispatched: ${result.nonCriticalDispatched}`,
+    );
+  }
+
+  private async processOrder(orderId: string, command: PlaceOrderCommand): Promise<void> {
+    // Order processing logic here
+  }
+}
+```
+
+#### 4. Event Execution Flow
+
+```
+publish(OrderPlacedEvent)
+    │
+    ├─► Critical Consumers (sequential, awaited)
+    │   ├─► ValidateInventoryConsumer (order: 1) ✓
+    │   ├─► ReserveInventoryConsumer (order: 2) ✓  [has compensate()]
+    │   ├─► CreateOrderRecordConsumer (order: 3) ✓ [has compensate()]
+    │   └─► ChargePaymentConsumer (order: 4) ✗ FAILS
+    │
+    │   On failure → Run compensations in REVERSE order:
+    │   ├─► CreateOrderRecordConsumer.compensate() - deletes order
+    │   └─► ReserveInventoryConsumer.compensate() - releases inventory
+    │   Then throw original error
+    │
+    └─► Non-Critical Consumers (parallel, fire-and-forget)
+        ├─► SendOrderConfirmationConsumer
+        ├─► NotifyWarehouseConsumer
+        └─► TrackAnalyticsConsumer
+
+        Only runs if ALL critical consumers succeed
+        Failures logged but don't affect the result
+```
+
+#### 5. Compensation Pattern (Saga)
+
+Critical consumers can implement the `ICriticalEventConsumer` interface with an optional `compensate()` method to support saga-style rollback:
+
+```typescript
+import { ICriticalEventConsumer, EventHandler, Critical } from '@rolandsall24/nest-mediator';
+
+@Injectable()
+@EventHandler(OrderPlacedEvent)
+@Critical({ order: 3 })
+export class CreateOrderRecordConsumer implements ICriticalEventConsumer<OrderPlacedEvent> {
+  async handle(event: OrderPlacedEvent): Promise<void> {
+    // Create order in database
+    await this.orderRepository.create({
+      id: event.orderId,
+      customerId: event.customerId,
+      items: event.items,
+      total: event.total,
+    });
+  }
+
+  async compensate(event: OrderPlacedEvent): Promise<void> {
+    // Rollback: delete the order record
+    await this.orderRepository.delete(event.orderId);
+  }
+}
+```
+
+**Compensation rules:**
+- Only called when a **subsequent** critical consumer fails (not if this consumer fails)
+- Runs in **reverse order** (last succeeded → first succeeded)
+- Receives the same event instance passed to `handle()`
+- Should be **idempotent** - safe to run multiple times
+- Errors in compensations are logged but don't stop other compensations
+- Non-critical consumers don't need compensation (they're fire-and-forget)
+
+#### 6. Register Event Consumers
+
+Add consumers to your module providers - they're auto-discovered via `@EventHandler`:
+
+```typescript
+@Module({
+  imports: [NestMediatorModule.forRoot()],
+  providers: [
+    // Command handlers
+    PlaceOrderHandler,
+
+    // Event consumers - auto-discovered
+    ValidateInventoryConsumer,
+    ReserveInventoryConsumer,
+    CreateOrderRecordConsumer,
+    SendOrderConfirmationConsumer,
+    NotifyWarehouseConsumer,
+    TrackAnalyticsConsumer,
+  ],
+})
+export class AppModule {}
+```
+
 ## Complete Example
 
 Here's a complete example following Domain-Driven Design principles with proper separation of concerns:
@@ -682,6 +937,63 @@ export interface IPipelineBehavior<TRequest = any, TResponse = any> {
 }
 ```
 
+#### `IEvent`
+
+Marker interface for domain events.
+
+```typescript
+export interface IEvent {}
+```
+
+#### `IEventConsumer<TEvent>`
+
+Interface for event consumers (non-critical or critical without compensation).
+
+```typescript
+export interface IEventConsumer<TEvent extends IEvent> {
+  handle(event: TEvent): Promise<void>;
+}
+```
+
+#### `ICriticalEventConsumer<TEvent>`
+
+Interface for critical event consumers with optional compensation support (saga pattern).
+
+```typescript
+export interface ICriticalEventConsumer<TEvent extends IEvent> extends IEventConsumer<TEvent> {
+  /**
+   * Compensate/rollback the work done by handle().
+   * Called when a subsequent critical consumer fails.
+   * Should be idempotent and derive state from the event.
+   */
+  compensate?(event: TEvent): Promise<void>;
+}
+```
+
+#### `EventPublishResult`
+
+Result returned by `publish()`.
+
+```typescript
+export interface EventPublishResult {
+  totalHandlers: number;
+  criticalSucceeded: number;
+  nonCriticalDispatched: number;
+  compensationsRun: number;  // Number of compensations executed on failure
+}
+```
+
+#### `EventCriticality`
+
+Enum for event consumer criticality.
+
+```typescript
+export enum EventCriticality {
+  CRITICAL = 'critical',
+  NON_CRITICAL = 'non-critical',
+}
+```
+
 ### Decorators
 
 #### `@CommandHandler(command)`
@@ -707,6 +1019,38 @@ Marks a class as a pipeline behavior.
   - `options.scope` - `'command'`, `'query'`, or `'all'` (default: `'all'`)
 - **Usage**: Apply to behavior classes that implement `IPipelineBehavior`
 
+#### `@Handle()`
+
+Method decorator that enables automatic request type inference for pipeline behaviors.
+
+- **Parameters**: None
+- **Usage**: Apply to the `handle` method to make the behavior type-specific
+
+```typescript
+// Generic behavior - applies to ALL requests in scope
+@Injectable()
+@PipelineBehavior({ priority: 0 })
+export class LoggingBehavior<TRequest, TResponse>
+  implements IPipelineBehavior<TRequest, TResponse> {
+  async handle(request: TRequest, next: () => Promise<TResponse>) {
+    // Runs for all requests
+    return next();
+  }
+}
+
+// Type-specific behavior - applies ONLY to CreateUserCommand
+@Injectable()
+@PipelineBehavior({ priority: 100, scope: 'command' })
+export class CreateUserValidationBehavior
+  implements IPipelineBehavior<CreateUserCommand, void> {
+  @Handle()  // <-- Enables type inference
+  async handle(request: CreateUserCommand, next: () => Promise<void>) {
+    // Only runs for CreateUserCommand
+    return next();
+  }
+}
+```
+
 #### `@SkipBehavior(behavior | behaviors[])`
 
 Excludes specific pipeline behaviors from a command or query.
@@ -717,11 +1061,36 @@ Excludes specific pipeline behaviors from a command or query.
 - **Usage**: Apply to command or query classes
 - **Works with**: Both built-in behaviors and custom behaviors
 
+#### `@EventHandler(event)`
+
+Marks a class as an event consumer.
+
+- **Parameters**: `event` - The event class this consumer handles
+- **Usage**: Apply to consumer classes that implement `IEventConsumer`
+
+#### `@Critical(options?)`
+
+Marks an event consumer as critical. Critical consumers run sequentially in order.
+
+- **Parameters**:
+  - `options.order` - Execution order among critical consumers (lower numbers first, default: 0)
+- **Usage**: Apply to consumer classes alongside `@EventHandler`
+- **Behavior**: If a critical consumer fails, remaining critical consumers are skipped and non-critical consumers don't run
+
+#### `@NonCritical()`
+
+Marks an event consumer as non-critical. Non-critical consumers run in parallel after critical consumers complete.
+
+- **Parameters**: None
+- **Usage**: Apply to consumer classes alongside `@EventHandler`
+- **Behavior**: Fire-and-forget - failures are logged but don't affect the publish result
+- **Note**: Consumers without `@Critical` or `@NonCritical` default to non-critical
+
 ### Services
 
 #### `MediatorBus`
 
-The main service for sending commands and queries.
+The main service for sending commands, queries, and events.
 
 ##### Methods
 
@@ -731,7 +1100,7 @@ Sends a command to its registered handler.
 
 - **Parameters**: `command` - The command instance to execute
 - **Returns**: Promise that resolves when the command is executed
-- **Throws**: Error if no handler is registered for the command
+- **Throws**: `HandlerNotFoundException` if no handler is registered for the command
 
 **`query<TQuery, TResult>(query: TQuery): Promise<TResult>`**
 
@@ -739,7 +1108,18 @@ Executes a query through its registered handler.
 
 - **Parameters**: `query` - The query instance to execute
 - **Returns**: Promise that resolves with the query result
-- **Throws**: Error if no handler is registered for the query
+- **Throws**: `HandlerNotFoundException` if no handler is registered for the query
+
+**`publish<TEvent>(event: TEvent): Promise<EventPublishResult>`**
+
+Publishes an event to all registered consumers.
+
+- **Parameters**: `event` - The event instance to publish
+- **Returns**: Promise with `EventPublishResult` containing:
+  - `totalHandlers` - Total number of consumers
+  - `criticalSucceeded` - Number of critical consumers that completed
+  - `nonCriticalDispatched` - Number of non-critical consumers dispatched
+- **Throws**: Error if any critical consumer fails
 
 ### Module Configuration
 
@@ -1044,6 +1424,65 @@ export class AuthorizationBehavior<TRequest, TResponse>
 }
 ```
 
+### Type-Specific Behaviors
+
+By default, behaviors apply to all requests matching their scope. To create a behavior that only applies to specific request types, add `@Handle()` to the `handle` method:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { IPipelineBehavior, PipelineBehavior, Handle } from '@rolandsall24/nest-mediator';
+import { CreateUserCommand } from './create-user.command';
+
+@Injectable()
+@PipelineBehavior({ priority: 95, scope: 'command' })
+export class CreateUserValidationBehavior
+  implements IPipelineBehavior<CreateUserCommand, void>
+{
+  @Handle()  // Enables type inference from method signature
+  async handle(
+    request: CreateUserCommand,
+    next: () => Promise<void>,
+  ): Promise<void> {
+    // This behavior ONLY runs for CreateUserCommand instances
+    // No manual instanceof check needed!
+
+    const errors: string[] = [];
+
+    if (!request.name || request.name.length < 2) {
+      errors.push('Name must be at least 2 characters');
+    }
+
+    if (!request.email || !request.email.includes('@')) {
+      errors.push('Valid email is required');
+    }
+
+    if (errors.length > 0) {
+      throw new Error(`Validation failed: ${errors.join(', ')}`);
+    }
+
+    return next();
+  }
+}
+```
+
+**How it works:**
+
+1. The `@Handle()` decorator on the `handle` method triggers TypeScript to emit `design:paramtypes` metadata
+2. At module initialization, the library reads this metadata to determine the request type (`CreateUserCommand`)
+3. During pipeline execution, the behavior is only included when `request instanceof CreateUserCommand` is true
+
+**Requirements:**
+- TypeScript `emitDecoratorMetadata: true` must be enabled in tsconfig.json
+- The request parameter must be a concrete class (not an interface or `any`)
+
+**Comparison:**
+
+| Without `@Handle()` | With `@Handle()` |
+|---------------------|------------------|
+| Behavior runs for ALL commands | Behavior runs ONLY for specified type |
+| Must use `instanceof` check inside handler | No `instanceof` check needed |
+| Generic `<TRequest, TResponse>` | Specific type like `<CreateUserCommand, void>` |
+
 ### Complete Behavior Execution Order Example
 
 With the following behaviors configured:
@@ -1097,6 +1536,124 @@ export class CreateUserCommand implements ICommand {
 // If validation fails, ValidationException is thrown with details
 ```
 
+### How `next()` Works in Pipeline Behaviors
+
+The `next()` function is a delegate that invokes the next behavior in the pipeline (or the final handler). Here's how it works:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        REQUEST FLOW (→)                                  │
+│                                                                          │
+│  Request                                                                 │
+│     │                                                                    │
+│     ▼                                                                    │
+│  ┌──────────────────────┐                                               │
+│  │  Behavior A          │  1. Pre-processing (before next())            │
+│  │  (priority: -100)    │     - Wrap in try/catch                       │
+│  │                      │     - Start timer                             │
+│  │  return next() ──────┼──►                                            │
+│  └──────────────────────┘                                               │
+│                              │                                           │
+│                              ▼                                           │
+│                         ┌──────────────────────┐                        │
+│                         │  Behavior B          │  2. Pre-processing     │
+│                         │  (priority: 0)       │     - Log request      │
+│                         │                      │                        │
+│                         │  return next() ──────┼──►                     │
+│                         └──────────────────────┘                        │
+│                                                    │                     │
+│                                                    ▼                     │
+│                                               ┌──────────────────────┐  │
+│                                               │  Behavior C          │  │
+│                                               │  (priority: 100)     │  │
+│                                               │                      │  │
+│                                               │  return next() ──────┼──►
+│                                               └──────────────────────┘  │
+│                                                                         │
+│                                                    │                     │
+│                                                    ▼                     │
+│                                               ┌──────────────────────┐  │
+│                                               │      HANDLER         │  │
+│                                               │   execute(request)   │  │
+│                                               │                      │  │
+│                                               │  return result ◄─────┼──┤
+│                                               └──────────────────────┘  │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       RESPONSE FLOW (←)                                  │
+│                                                                          │
+│  ┌──────────────────────┐                                               │
+│  │  Behavior A          │  4. Post-processing (after next() returns)    │
+│  │  (priority: -100)    │     - Catch errors                            │
+│  │                      │     - Calculate duration                      │
+│  │  ◄── result ─────────┼──                                             │
+│  └──────────────────────┘                                               │
+│         │                    ▲                                           │
+│         ▼                    │                                           │
+│      Response           ┌──────────────────────┐                        │
+│                         │  Behavior B          │  3. Post-processing    │
+│                         │  (priority: 0)       │     - Log response     │
+│                         │                      │     - Log duration     │
+│                         │  ◄── result ─────────┼──                      │
+│                         └──────────────────────┘                        │
+│                                                    ▲                     │
+│                                                    │                     │
+│                                               ┌──────────────────────┐  │
+│                                               │  Behavior C          │  │
+│                                               │  (priority: 100)     │  │
+│                                               │                      │  │
+│                                               │  ◄── result ─────────┼──┤
+│                                               └──────────────────────┘  │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Code Example:**
+
+```typescript
+@Injectable()
+@PipelineBehavior({ priority: 0 })
+export class LoggingBehavior<TRequest, TResponse>
+  implements IPipelineBehavior<TRequest, TResponse>
+{
+  async handle(
+    request: TRequest,
+    next: () => Promise<TResponse>  // Delegate to next behavior/handler
+  ): Promise<TResponse> {
+    // ═══════════════════════════════════════════
+    // PRE-PROCESSING (runs BEFORE the handler)
+    // ═══════════════════════════════════════════
+    const start = Date.now();
+    console.log(`→ Handling ${request.constructor.name}...`);
+
+    // ═══════════════════════════════════════════
+    // CALL NEXT (invokes next behavior or handler)
+    // ═══════════════════════════════════════════
+    const response = await next();
+
+    // ═══════════════════════════════════════════
+    // POST-PROCESSING (runs AFTER the handler)
+    // ═══════════════════════════════════════════
+    const duration = Date.now() - start;
+    console.log(`← Handled ${request.constructor.name} in ${duration}ms`);
+
+    return response;
+  }
+}
+```
+
+**Key Points:**
+
+1. **`next()` is a function** that returns a `Promise` - you must `await` it
+2. **Code before `await next()`** runs during the request phase (pre-processing)
+3. **Code after `await next()`** runs during the response phase (post-processing)
+4. **Lower priority = outer wrapper** - executes first on request, last on response
+5. **Higher priority = inner wrapper** - executes last on request, first on response
+6. **If you don't call `next()`**, the handler never executes (useful for short-circuiting)
+7. **Exceptions propagate outward** through the `await next()` chain
+
 ### Pipeline Execution Order
 
 With behaviors at priorities -100, 0, 10, 100: