CQRS API

Enhanced NestJS CQRS with event sagas, dead-letter queue, and type-safe event handling.

What It Does

The CQRS API provides an enhanced version of NestJS CQRS that adds event sagas for event transformation, dead-letter queue retry mechanisms for failed commands, and fixes for NestJS CQRS typing issues. It enables event-driven architecture with resilient command handling and automatic error tracking.

Key Capabilities

Capability	Description
Event Sagas	Transform database events into domain events with RxJS operators
Dead-Letter Queue	Automatic retry mechanism for failed commands
Type-Safe Events	Fixes NestJS CQRS typing issues across module boundaries
Error Tracking	Integrated logging and error reporting
Infinite Loop Prevention	Automatically filters events to prevent saga loops
Dynamic Command Execution	Execute arbitrary functions through CQRS bus
Reporting Event Handler	Base class with automatic error reporting
Retry Command Handler	Resilient command handling with DLQ support
Explorer Service	Automatic discovery and registration of event sagas

Configuration

Module Options

serviceId: Service identifier (required)
queue: DLQ queue name (default: ‘cqrs-retry’)
endpoint: DLQ retry endpoint (default: ‘/tasks/cqrs/retry-dead-letter’)

Dead-Letter Queue

Stores failed commands with handler metadata
Enables manual or automatic retry
Integrated with Foundation tasks service

Exports

Module

Eng11CqrsModule - Enhanced CQRS module

Base Classes

ReportingEventHandler - Event handler with error reporting
RetryCommandHandler - Command handler with DLQ support

Decorators

@EventSaga(EventType) - Event saga decorator

Commands

ExecuteCommand - Dynamic function execution

Operators

isOfType - Type-safe event filtering
logSagaError - Error logging for sagas

Interfaces

E11CqrsModuleOptions - Module configuration
IEventSaga - Event saga interface
IDeadLetter - Failed command model

Common Use Cases

Event-driven architecture: Transform database events into domain events
Microservice communication: Handle cross-service event flows
Resilient commands: Automatically retry failed commands via DLQ
Event transformation: Map one event type to multiple specific events
Error tracking: Automatic error logging for event and command handlers
Saga orchestration: Chain multiple event transformations
Command failure recovery: Dead-letter queue for manual intervention

What Customers Don’t Have to Build

Event saga infrastructure
Event transformation pipelines
Dead-letter queue system
Command retry mechanisms
Type-safe event filtering across modules
Automatic saga discovery and registration
Error reporting for handlers
RxJS error operators
Infinite loop prevention
Dynamic command execution
NestJS CQRS typing fixes
Module configuration patterns
Subscription lifecycle management
Explorer service for metadata discovery
DLQ controller endpoints