@signaltree/events 7.3.1

package/src/nestjs/base.subscriber.d.ts

@@ -0,0 +1,169 @@
+import { Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { ClassificationResult } from '../core/error-classification';
+import { IdempotencyStore } from '../core/idempotency';
+import { BaseEvent, EventPriority } from '../core/types';
+import { DlqService } from './dlq.service';
+import { EventBusModuleConfig } from './event-bus.module';
+/**
+ * Base Subscriber - Abstract class for event subscribers
+ *
+ * Provides:
+ * - Automatic idempotency checking
+ * - Retry with exponential backoff
+ * - Error classification and DLQ routing
+ * - Metrics collection
+ * - Graceful shutdown
+ */
+/**
+ * Subscriber configuration
+ */
+export interface SubscriberConfig {
+    /** Unique subscriber name */
+    name: string;
+    /** Event types to subscribe to */
+    eventTypes: string[];
+    /** Queue to process from (or use priority to auto-select) */
+    queue?: string;
+    /** Priority level (used to select queue if queue not specified) */
+    priority?: EventPriority;
+    /** Number of concurrent jobs to process */
+    concurrency?: number;
+    /** Lock duration in ms (how long a job is locked while processing) */
+    lockDuration?: number;
+    /** Stalled check interval in ms */
+    stalledInterval?: number;
+    /** Enable idempotency checking (default: true) */
+    idempotency?: boolean;
+    /** Skip DLQ for this subscriber */
+    skipDlq?: boolean;
+}
+/**
+ * Result of processing an event
+ */
+export interface ProcessingResult {
+    /** Whether processing succeeded */
+    success: boolean;
+    /** Optional result data (stored for idempotent responses) */
+    result?: unknown;
+    /** Error if failed */
+    error?: Error;
+    /** Whether to skip DLQ (useful for expected failures) */
+    skipDlq?: boolean;
+    /** Custom retry delay override */
+    retryDelay?: number;
+}
+/**
+ * Subscriber metrics
+ */
+export interface SubscriberMetrics {
+    processed: number;
+    succeeded: number;
+    failed: number;
+    retried: number;
+    dlqSent: number;
+    duplicatesSkipped: number;
+    avgProcessingTimeMs: number;
+    lastProcessedAt?: Date;
+}
+/**
+ * Base class for event subscribers
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class TradeSubscriber extends BaseSubscriber {
+ *   protected readonly config: SubscriberConfig = {
+ *     name: 'trade-subscriber',
+ *     eventTypes: ['TradeProposalCreated', 'TradeAccepted'],
+ *     priority: 'high',
+ *     concurrency: 5,
+ *   };
+ *
+ *   async handle(event: TradeProposalCreated | TradeAccepted): Promise<ProcessingResult> {
+ *     switch (event.type) {
+ *       case 'TradeProposalCreated':
+ *         await this.handleTradeCreated(event);
+ *         break;
+ *       case 'TradeAccepted':
+ *         await this.handleTradeAccepted(event);
+ *         break;
+ *     }
+ *     return { success: true };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseSubscriber<TEvent extends BaseEvent = BaseEvent> implements OnModuleInit, OnModuleDestroy {
+    protected readonly busConfig: EventBusModuleConfig;
+    protected readonly idempotencyStore: IdempotencyStore;
+    protected readonly errorClassifier: {
+        classify: (e: unknown) => ClassificationResult;
+    };
+    protected readonly dlqService: DlqService;
+    protected readonly logger: Logger;
+    protected abstract readonly config: SubscriberConfig;
+    private worker?;
+    private connection;
+    private metrics;
+    constructor(busConfig: EventBusModuleConfig, idempotencyStore: IdempotencyStore, errorClassifier: {
+        classify: (e: unknown) => ClassificationResult;
+    }, dlqService: DlqService);
+    /**
+     * Handle the event - implement in subclass
+     */
+    protected abstract handle(event: TEvent): Promise<ProcessingResult>;
+    /**
+     * Called before processing starts (for setup/validation)
+     */
+    protected beforeProcess(_event: TEvent): Promise<void>;
+    /**
+     * Called after processing completes (for cleanup)
+     */
+    protected afterProcess(_event: TEvent, _result: ProcessingResult): Promise<void>;
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    /**
+     * Get queue name based on config
+     */
+    protected getQueueName(): string;
+    /**
+     * Process a job with idempotency and error handling
+     */
+    private processJob;
+    /**
+     * Handle processing error
+     */
+    private handleError;
+    /**
+     * Check idempotency
+     */
+    private checkIdempotency;
+    /**
+     * Send failed event to DLQ
+     */
+    private sendToDlq;
+    /**
+     * Update metrics
+     */
+    private updateMetrics;
+    /**
+     * Setup worker event listeners
+     */
+    private setupWorkerListeners;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): SubscriberMetrics;
+    /**
+     * Pause processing
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume processing
+     */
+    resume(): Promise<void>;
+    /**
+     * Check if worker is running
+     */
+    isRunning(): boolean;
+}

package/src/nestjs/decorators.d.ts

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+import { EventPriority } from '../core/types';
+/**
+ * Decorators for event handling
+ */
+/**
+ * Metadata key for event handlers
+ */
+export declare const EVENT_HANDLER_METADATA = "EVENT_HANDLER_METADATA";
+/**
+ * Event handler metadata
+ */
+export interface EventHandlerMetadata {
+    /** Event type to handle */
+    eventType: string;
+    /** Queue to listen on (derived from priority if not specified) */
+    queue?: string;
+    /** Priority level */
+    priority?: EventPriority;
+    /** Consumer group name */
+    consumerGroup?: string;
+}
+/**
+ * Decorator to mark a method as an event handler
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class TradeSubscriber extends BaseSubscriber {
+ *   @OnEvent('TradeProposalCreated', { priority: 'high' })
+ *   async handleTradeCreated(event: TradeProposalCreated) {
+ *     // Handle the event
+ *   }
+ * }
+ * ```
+ */
+export declare function OnEvent(eventType: string, options?: Omit<EventHandlerMetadata, 'eventType'>): MethodDecorator;

package/src/nestjs/dlq.service.d.ts

@@ -0,0 +1,117 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { ErrorClassification } from '../core/error-classification';
+import { BaseEvent } from '../core/types';
+import { EventBusModuleConfig } from './event-bus.module';
+/**
+ * DLQ Service - Dead Letter Queue management
+ *
+ * Provides:
+ * - Send failed events to DLQ
+ * - Query and inspect DLQ entries
+ * - Replay events from DLQ
+ * - Purge old entries
+ */
+/**
+ * Entry in the Dead Letter Queue
+ */
+export interface DlqEntry<TEvent extends BaseEvent = BaseEvent> {
+    /** The failed event */
+    event: TEvent;
+    /** Error information */
+    error: {
+        message: string;
+        stack?: string;
+        classification: ErrorClassification;
+        reason: string;
+    };
+    /** Subscriber that failed */
+    subscriber: string;
+    /** Number of attempts before giving up */
+    attempts: number;
+    /** When the event was sent to DLQ */
+    failedAt: string;
+    /** Original queue the event was in */
+    originalQueue?: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Options for querying DLQ
+ */
+export interface DlqQueryOptions {
+    /** Filter by event type */
+    eventType?: string;
+    /** Filter by subscriber */
+    subscriber?: string;
+    /** Filter by error classification */
+    classification?: ErrorClassification;
+    /** Filter by date range */
+    from?: Date;
+    to?: Date;
+    /** Pagination */
+    start?: number;
+    end?: number;
+}
+/**
+ * DLQ statistics
+ */
+export interface DlqStats {
+    total: number;
+    byEventType: Record<string, number>;
+    bySubscriber: Record<string, number>;
+    byClassification: Record<ErrorClassification, number>;
+    oldestEntry?: Date;
+    newestEntry?: Date;
+}
+export declare class DlqService implements OnModuleInit, OnModuleDestroy {
+    private readonly config;
+    private readonly logger;
+    private queue?;
+    private queueName;
+    constructor(config: EventBusModuleConfig);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    /**
+     * Send an event to the DLQ
+     */
+    send(entry: DlqEntry): Promise<string>;
+    /**
+     * Get entries from DLQ
+     */
+    getEntries(options?: DlqQueryOptions): Promise<DlqEntry[]>;
+    /**
+     * Get a specific entry by event ID
+     */
+    getEntry(eventId: string, subscriber?: string): Promise<DlqEntry | null>;
+    /**
+     * Get DLQ statistics
+     */
+    getStats(): Promise<DlqStats>;
+    /**
+     * Replay an event from DLQ
+     *
+     * This removes the event from DLQ and republishes to original queue
+     */
+    replay(eventId: string, subscriber: string, targetQueue: string): Promise<boolean>;
+    /**
+     * Replay all events matching criteria
+     */
+    replayBatch(options: DlqQueryOptions & {
+        targetQueue: string;
+    }): Promise<{
+        replayed: number;
+        failed: number;
+    }>;
+    /**
+     * Remove an entry from DLQ
+     */
+    remove(eventId: string, subscriber: string): Promise<boolean>;
+    /**
+     * Purge old entries from DLQ
+     */
+    purge(olderThan: Date): Promise<number>;
+    /**
+     * Clear all entries from DLQ
+     */
+    clear(): Promise<number>;
+}

package/src/nestjs/event-bus.module.d.ts

@@ -0,0 +1,117 @@
+import { DynamicModule, InjectionToken, OptionalFactoryDependency, Type } from '@nestjs/common';
+import { ErrorClassifierConfig, EventRegistryConfig, IdempotencyStore } from '..';
+/**
+ * EventBus Module - NestJS module for event-driven architecture
+ *
+ * Provides:
+ * - BullMQ queue integration
+ * - Event publishing with priority routing
+ * - Idempotency and retry handling
+ * - DLQ management
+ */
+/**
+ * Redis connection configuration
+ */
+export interface RedisConfig {
+    host: string;
+    port: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+    maxRetriesPerRequest?: number;
+}
+/**
+ * Queue configuration
+ */
+export interface QueueConfig {
+    /** Queue name */
+    name: string;
+    /** Priority levels routed to this queue */
+    priorities: string[];
+    /** Concurrency for this queue */
+    concurrency?: number;
+    /** Rate limit per interval */
+    rateLimit?: {
+        max: number;
+        duration: number;
+    };
+}
+/**
+ * EventBus module configuration
+ */
+export interface EventBusModuleConfig {
+    /** Redis connection config */
+    redis: RedisConfig;
+    /** Queue configuration (defaults to priority-based queues) */
+    queues?: QueueConfig[];
+    /** Event registry configuration */
+    registry?: EventRegistryConfig;
+    /** Custom idempotency store (defaults to in-memory) */
+    idempotencyStore?: IdempotencyStore;
+    /** Error classifier configuration */
+    errorClassifier?: ErrorClassifierConfig;
+    /** Enable DLQ (default: true) */
+    enableDlq?: boolean;
+    /** DLQ queue name (default: 'dead-letter') */
+    dlqQueueName?: string;
+    /** Global concurrency limit */
+    globalConcurrency?: number;
+    /** Enable metrics (default: true) */
+    enableMetrics?: boolean;
+    /** Metrics prefix */
+    metricsPrefix?: string;
+}
+/**
+ * Async configuration options
+ */
+export interface EventBusModuleAsyncConfig {
+    imports?: Type<unknown>[];
+    useFactory: (...args: unknown[]) => Promise<EventBusModuleConfig> | EventBusModuleConfig;
+    inject?: (InjectionToken | OptionalFactoryDependency)[];
+}
+export declare class EventBusModule {
+    /**
+     * Register the EventBus module with configuration
+     *
+     * @example
+     * ```typescript
+     * @Module({
+     *   imports: [
+     *     EventBusModule.forRoot({
+     *       redis: { host: 'localhost', port: 6379 },
+     *       queues: [
+     *         { name: 'critical', priorities: ['critical'], concurrency: 10 },
+     *         { name: 'normal', priorities: ['high', 'normal'], concurrency: 5 },
+     *       ],
+     *     }),
+     *   ],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRoot(config: EventBusModuleConfig): DynamicModule;
+    /**
+     * Register the EventBus module with async configuration
+     *
+     * @example
+     * ```typescript
+     * @Module({
+     *   imports: [
+     *     EventBusModule.forRootAsync({
+     *       imports: [ConfigModule],
+     *       useFactory: (configService: ConfigService) => ({
+     *         redis: {
+     *           host: configService.get('REDIS_HOST'),
+     *           port: configService.get('REDIS_PORT'),
+     *         },
+     *       }),
+     *       inject: [ConfigService],
+     *     }),
+     *   ],
+     * })
+     * export class AppModule {}
+     * ```
+     */
+    static forRootAsync(asyncConfig: EventBusModuleAsyncConfig): DynamicModule;
+    private static createProviders;
+}

package/src/nestjs/event-bus.service.d.ts

@@ -0,0 +1,114 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { Queue } from 'bullmq';
+import { EventRegistry } from '../core/registry';
+import { BaseEvent, EventPriority } from '../core/types';
+import { EventBusModuleConfig } from './event-bus.module';
+/**
+ * EventBus Service - Publish events to BullMQ queues
+ *
+ * Provides:
+ * - Event publishing with validation
+ * - Priority-based routing
+ * - Correlation ID propagation
+ * - Metrics collection
+ */
+/**
+ * Options for publishing an event
+ */
+export interface PublishOptions {
+    /** Override event ID */
+    id?: string;
+    /** Correlation ID for request tracing */
+    correlationId?: string;
+    /** Causation ID (parent event) */
+    causationId?: string;
+    /** Delay before processing (ms) */
+    delay?: number;
+    /** Override priority */
+    priority?: EventPriority;
+    /** Specific queue to publish to */
+    queue?: string;
+    /** Job ID for deduplication */
+    jobId?: string;
+    /** Custom job options */
+    jobOptions?: Record<string, unknown>;
+}
+/**
+ * Result of publishing an event
+ */
+export interface PublishResult {
+    /** Event ID */
+    eventId: string;
+    /** BullMQ Job ID */
+    jobId: string;
+    /** Queue the event was published to */
+    queue: string;
+    /** Correlation ID */
+    correlationId: string;
+}
+export declare class EventBusService implements OnModuleInit, OnModuleDestroy {
+    private readonly config;
+    private readonly registry;
+    private readonly logger;
+    private queues;
+    private priorityToQueue;
+    private connection;
+    private isReady;
+    constructor(config: EventBusModuleConfig, registry: EventRegistry);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    /**
+     * Publish an event
+     *
+     * @example
+     * ```typescript
+     * await eventBus.publish({
+     *   type: 'TradeProposalCreated',
+     *   data: {
+     *     tradeId: '123',
+     *     initiatorId: 'user-1',
+     *     recipientId: 'user-2',
+     *   },
+     * });
+     * ```
+     */
+    publish<T extends BaseEvent>(event: Omit<T, 'id' | 'timestamp'> & Partial<Pick<T, 'id' | 'timestamp'>>, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * Publish multiple events in a batch
+     */
+    publishBatch<T extends BaseEvent>(events: Array<Omit<T, 'id' | 'timestamp'> & Partial<Pick<T, 'id' | 'timestamp'>>>, options?: Omit<PublishOptions, 'id' | 'jobId'>): Promise<PublishResult[]>;
+    /**
+     * Get queue for a given priority
+     */
+    getQueueForPriority(priority: EventPriority): string;
+    /**
+     * Get queue stats
+     */
+    getQueueStats(queueName: string): Promise<{
+        waiting: number;
+        active: number;
+        completed: number;
+        failed: number;
+        delayed: number;
+    }>;
+    /**
+     * Get all queue names
+     */
+    getQueueNames(): string[];
+    /**
+     * Get underlying BullMQ queue for advanced operations
+     */
+    getQueue(name: string): Queue | undefined;
+    /**
+     * Check if service is ready
+     */
+    isServiceReady(): boolean;
+    /**
+     * Convert priority string to number for BullMQ (lower = higher priority)
+     */
+    private getPriorityNumber;
+    /**
+     * Setup event listeners for monitoring
+     */
+    private setupQueueEventListeners;
+}

package/src/nestjs/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @signaltree/events/nestjs
+ *
+ * NestJS integration for event-driven architecture.
+ * Provides EventBusModule, BaseSubscriber, and DLQ handling.
+ */
+export { EventBusModule } from './event-bus.module';
+export type { EventBusModuleConfig, EventBusModuleAsyncConfig, } from './event-bus.module';
+export { EventBusService } from './event-bus.service';
+export type { PublishOptions, PublishResult } from './event-bus.service';
+export { BaseSubscriber } from './base.subscriber';
+export type { SubscriberConfig, ProcessingResult, SubscriberMetrics, } from './base.subscriber';
+export { DlqService } from './dlq.service';
+export type { DlqEntry, DlqQueryOptions, DlqStats } from './dlq.service';
+export { OnEvent, EVENT_HANDLER_METADATA } from './decorators';
+export { EVENT_BUS_CONFIG, EVENT_REGISTRY, IDEMPOTENCY_STORE, ERROR_CLASSIFIER, } from './tokens';

package/src/nestjs/tokens.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Injection tokens for the EventBus module
+ */
+export declare const EVENT_BUS_CONFIG: unique symbol;
+export declare const EVENT_REGISTRY: unique symbol;
+export declare const IDEMPOTENCY_STORE: unique symbol;
+export declare const ERROR_CLASSIFIER: unique symbol;
+export declare const DLQ_SERVICE: unique symbol;

package/src/nestjs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @signaltree/events/nestjs
+ *
+ * Re-export barrel for NestJS integration.
+ * This file exists for build tooling - import from '@signaltree/events/nestjs'
+ */
+export * from './nestjs/index';

package/src/testing/assertions.d.ts

@@ -0,0 +1,113 @@
+import { BaseEvent } from '../core/types';
+import { PublishedEvent } from './mock-event-bus';
+/**
+ * Test Assertions - Assertion helpers for event testing
+ *
+ * Provides:
+ * - Fluent assertion API
+ * - Event structure validation
+ * - Sequence assertions
+ */
+/**
+ * Assertion result
+ */
+export interface AssertionResult {
+    passed: boolean;
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+/**
+ * Event assertions class
+ */
+export declare class EventAssertions {
+    private publishedEvents;
+    constructor(events: PublishedEvent[]);
+    /**
+     * Assert that an event was published
+     */
+    toHavePublished(eventType: string): AssertionResult;
+    /**
+     * Assert that an event was NOT published
+     */
+    toNotHavePublished(eventType: string): AssertionResult;
+    /**
+     * Assert the number of published events
+     */
+    toHavePublishedCount(count: number, eventType?: string): AssertionResult;
+    /**
+     * Assert event was published with specific data
+     */
+    toHavePublishedWith<T extends BaseEvent>(eventType: T['type'], predicate: (event: T) => boolean): AssertionResult;
+    /**
+     * Assert events were published in order
+     */
+    toHavePublishedInOrder(eventTypes: string[]): AssertionResult;
+    /**
+     * Assert event has valid structure
+     */
+    toBeValidEvent<T extends BaseEvent>(event: T): AssertionResult;
+    /**
+     * Assert all events have same correlation ID
+     */
+    toHaveSameCorrelationId(): AssertionResult;
+    /**
+     * Assert event was published to specific queue
+     */
+    toHavePublishedToQueue(eventType: string, queue: string): AssertionResult;
+    /**
+     * Get all assertions as an array
+     */
+    getAllResults(): AssertionResult[];
+}
+/**
+ * Create event assertions helper
+ *
+ * @example
+ * ```typescript
+ * const eventBus = createMockEventBus();
+ * // ... publish events ...
+ *
+ * const assertions = createEventAssertions(eventBus.getPublishedEvents());
+ *
+ * expect(assertions.toHavePublished('TradeCreated').passed).toBe(true);
+ * expect(assertions.toHavePublishedCount(3).passed).toBe(true);
+ * expect(assertions.toHavePublishedInOrder(['TradeCreated', 'TradeAccepted']).passed).toBe(true);
+ * ```
+ */
+export declare function createEventAssertions(events: PublishedEvent[]): EventAssertions;
+/**
+ * Jest/Vitest custom matcher helpers
+ *
+ * @example
+ * ```typescript
+ * // In your test setup
+ * expect.extend({
+ *   toHavePublishedEvent(received: MockEventBus, eventType: string) {
+ *     const assertions = createEventAssertions(received.getPublishedEvents());
+ *     const result = assertions.toHavePublished(eventType);
+ *     return {
+ *       pass: result.passed,
+ *       message: () => result.message,
+ *     };
+ *   },
+ * });
+ *
+ * // In your test
+ * expect(eventBus).toHavePublishedEvent('TradeCreated');
+ * ```
+ */
+export declare const jestMatchers: {
+    toHavePublishedEvent(received: {
+        getPublishedEvents: () => PublishedEvent[];
+    }, eventType: string): {
+        pass: boolean;
+        message: () => string;
+    };
+    toHavePublishedEventCount(received: {
+        getPublishedEvents: () => PublishedEvent[];
+    }, count: number, eventType?: string): {
+        pass: boolean;
+        message: () => string;
+    };
+};