@signaltree/events 7.3.1

package/src/testing/factories.d.ts

@@ -0,0 +1,106 @@
+import { BaseEvent, EventActor, EventMetadata, EventPriority, EventVersion } from '../core/types';
+/**
+ * Test Event Factories - Create events for testing
+ *
+ * Provides:
+ * - Type-safe event creation
+ * - Randomized data generation
+ * - Override support
+ */
+/**
+ * Options for creating test events
+ */
+export interface TestEventOptions {
+    /** Override event ID */
+    id?: string;
+    /** Override correlation ID */
+    correlationId?: string;
+    /** Override causation ID */
+    causationId?: string;
+    /** Override timestamp */
+    timestamp?: string;
+    /** Override actor */
+    actor?: Partial<EventActor>;
+    /** Override metadata */
+    metadata?: Partial<EventMetadata>;
+    /** Override priority */
+    priority?: EventPriority;
+    /** Override version */
+    version?: EventVersion;
+    /** Override aggregate */
+    aggregate?: {
+        type: string;
+        id: string;
+    };
+}
+/**
+ * Test event factory interface
+ */
+export interface TestEventFactory<TEvents extends BaseEvent = BaseEvent> {
+    /**
+     * Create a test event
+     */
+    create<T extends TEvents>(type: T['type'], data: T['data'], options?: TestEventOptions): T;
+    /**
+     * Create multiple test events
+     */
+    createMany<T extends TEvents>(type: T['type'], dataArray: T['data'][], options?: TestEventOptions): T[];
+    /**
+     * Create a test event with random data
+     * Override this in your app's test utilities
+     */
+    createRandom<T extends TEvents>(type: T['type'], overrides?: Partial<T['data']>, options?: TestEventOptions): T;
+}
+/**
+ * Create a test event
+ *
+ * @example
+ * ```typescript
+ * const event = createTestEvent('TradeProposalCreated', {
+ *   tradeId: '123',
+ *   initiatorId: 'user-1',
+ *   recipientId: 'user-2',
+ * });
+ * ```
+ */
+export declare function createTestEvent<TType extends string, TData>(type: TType, data: TData, options?: TestEventOptions): BaseEvent<TType, TData>;
+/**
+ * Create a test event factory
+ *
+ * @example
+ * ```typescript
+ * const factory = createTestEventFactory({
+ *   defaultActor: { id: 'test-user', type: 'user' },
+ *   defaultMetadata: { source: 'test-service' },
+ * });
+ *
+ * const event = factory.create('TradeProposalCreated', {
+ *   tradeId: '123',
+ * });
+ * ```
+ */
+export declare function createTestEventFactory(config?: {
+    defaultActor?: Partial<EventActor>;
+    defaultMetadata?: Partial<EventMetadata>;
+    randomGenerators?: Record<string, () => unknown>;
+}): TestEventFactory;
+/**
+ * Generate a random UUID for testing
+ */
+export declare function randomUuid(): string;
+/**
+ * Generate a random string for testing
+ */
+export declare function randomString(length?: number): string;
+/**
+ * Generate a random number for testing
+ */
+export declare function randomNumber(min?: number, max?: number): number;
+/**
+ * Generate a random date for testing
+ */
+export declare function randomDate(start?: Date, end?: Date): Date;
+/**
+ * Generate a random element from array
+ */
+export declare function randomFrom<T>(array: T[]): T;

package/src/testing/helpers.d.ts

@@ -0,0 +1,104 @@
+import { ClassificationResult, ErrorClassification, RetryConfig } from '../core/error-classification';
+import { IdempotencyStore, ProcessedEventRecord } from '../core/idempotency';
+import { BaseEvent } from '../core/types';
+import { MockEventBus } from './mock-event-bus';
+/**
+ * Test Helpers - Utility functions for testing
+ *
+ * Provides:
+ * - Event waiting utilities
+ * - Mock implementations
+ * - Test fixtures
+ */
+/**
+ * Wait for an event to be published
+ *
+ * @example
+ * ```typescript
+ * const eventPromise = waitForEvent(eventBus, 'TradeCreated');
+ * await performAction();
+ * const event = await eventPromise;
+ * expect(event.data.tradeId).toBe('123');
+ * ```
+ */
+export declare function waitForEvent<T extends BaseEvent>(eventBus: MockEventBus, eventType: T['type'], timeoutMs?: number): Promise<T>;
+/**
+ * Wait for multiple events to be published
+ *
+ * @example
+ * ```typescript
+ * const eventsPromise = waitForEvents(eventBus, ['TradeCreated', 'NotificationSent']);
+ * await performAction();
+ * const events = await eventsPromise;
+ * ```
+ */
+export declare function waitForEvents(eventBus: MockEventBus, eventTypes: string[], timeoutMs?: number): Promise<BaseEvent[]>;
+/**
+ * Collect events during an action
+ *
+ * @example
+ * ```typescript
+ * const events = await collectEvents(eventBus, async () => {
+ *   await createTrade();
+ *   await acceptTrade();
+ * });
+ * expect(events).toHaveLength(2);
+ * ```
+ */
+export declare function collectEvents(eventBus: MockEventBus, action: () => Promise<void>, eventTypes?: string[]): Promise<BaseEvent[]>;
+/**
+ * Create a mock idempotency store
+ *
+ * @example
+ * ```typescript
+ * const store = mockIdempotencyStore({
+ *   duplicateIds: ['event-1', 'event-2'],
+ * });
+ *
+ * const result = await store.check({ id: 'event-1' }, 'consumer');
+ * expect(result.isDuplicate).toBe(true);
+ * ```
+ */
+export declare function mockIdempotencyStore(options?: {
+    duplicateIds?: string[];
+    shouldAcquireLock?: boolean;
+    processedRecords?: Map<string, ProcessedEventRecord>;
+}): IdempotencyStore;
+/**
+ * Create a mock error classifier
+ *
+ * @example
+ * ```typescript
+ * const classifier = mockErrorClassifier({
+ *   defaultClassification: 'transient',
+ *   customClassifications: {
+ *     'ValidationError': 'permanent',
+ *     'NetworkError': 'transient',
+ *   },
+ * });
+ * ```
+ */
+export declare function mockErrorClassifier(options?: {
+    defaultClassification?: ErrorClassification;
+    customClassifications?: Record<string, ErrorClassification>;
+    retryConfig?: Partial<RetryConfig>;
+}): {
+    classify: (error: unknown) => ClassificationResult;
+    isRetryable: (error: unknown) => boolean;
+};
+/**
+ * Create a test delay helper
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Create a deferred promise for testing async flows
+ */
+export declare function createDeferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: Error) => void;
+};
+/**
+ * Flush pending promises (useful for testing)
+ */
+export declare function flushPromises(): Promise<void>;

package/src/testing/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @signaltree/events/testing
+ *
+ * Testing utilities for event-driven applications.
+ * Provides mocks, factories, and helpers for unit testing.
+ */
+export { MockEventBus, createMockEventBus } from './mock-event-bus';
+export type { MockEventBusOptions, PublishedEvent } from './mock-event-bus';
+export { createTestEvent, createTestEventFactory } from './factories';
+export type { TestEventFactory, TestEventOptions } from './factories';
+export { EventAssertions, createEventAssertions } from './assertions';
+export type { AssertionResult } from './assertions';
+export { waitForEvent, waitForEvents, collectEvents, mockIdempotencyStore, mockErrorClassifier, } from './helpers';

package/src/testing/mock-event-bus.d.ts

@@ -0,0 +1,144 @@
+import { BaseEvent } from '../core/types';
+/**
+ * Mock Event Bus - In-memory event bus for testing
+ *
+ * Provides:
+ * - Synchronous publish/subscribe
+ * - Event history tracking
+ * - Assertions and expectations
+ */
+/**
+ * Published event with metadata
+ */
+export interface PublishedEvent<T extends BaseEvent = BaseEvent> {
+    event: T;
+    queue: string;
+    publishedAt: Date;
+    delay?: number;
+}
+/**
+ * Subscription handler
+ */
+type SubscriptionHandler<T extends BaseEvent = BaseEvent> = (event: T) => void | Promise<void>;
+/**
+ * Mock EventBus options
+ */
+export interface MockEventBusOptions {
+    /** Simulate async behavior with delays */
+    simulateAsync?: boolean;
+    /** Delay for simulated async (ms) */
+    asyncDelayMs?: number;
+    /** Auto-generate missing event IDs */
+    autoGenerateIds?: boolean;
+    /** Throw on publish errors */
+    throwOnError?: boolean;
+}
+/**
+ * Mock Event Bus for testing
+ *
+ * @example
+ * ```typescript
+ * const eventBus = createMockEventBus();
+ *
+ * // Subscribe to events
+ * eventBus.subscribe('TradeProposalCreated', (event) => {
+ *   expect(event.data.tradeId).toBe('123');
+ * });
+ *
+ * // Publish an event
+ * await eventBus.publish({
+ *   type: 'TradeProposalCreated',
+ *   data: { tradeId: '123' },
+ * });
+ *
+ * // Assert published events
+ * expect(eventBus.getPublishedEvents()).toHaveLength(1);
+ * expect(eventBus.wasPublished('TradeProposalCreated')).toBe(true);
+ * ```
+ */
+export declare class MockEventBus {
+    private readonly options;
+    private publishedEvents;
+    private subscriptions;
+    private allSubscriptions;
+    constructor(options?: MockEventBusOptions);
+    /**
+     * Publish an event
+     */
+    publish<T extends BaseEvent>(event: Omit<T, 'id' | 'timestamp'> & Partial<Pick<T, 'id' | 'timestamp'>>, options?: {
+        queue?: string;
+        delay?: number;
+    }): Promise<{
+        eventId: string;
+        queue: string;
+    }>;
+    /**
+     * Publish multiple events
+     */
+    publishBatch<T extends BaseEvent>(events: Array<Omit<T, 'id' | 'timestamp'> & Partial<Pick<T, 'id' | 'timestamp'>>>, options?: {
+        queue?: string;
+    }): Promise<Array<{
+        eventId: string;
+        queue: string;
+    }>>;
+    /**
+     * Subscribe to a specific event type
+     */
+    subscribe<T extends BaseEvent>(eventType: T['type'], handler: SubscriptionHandler<T>): () => void;
+    /**
+     * Subscribe to all events
+     */
+    subscribeAll(handler: SubscriptionHandler): () => void;
+    /**
+     * Get all published events
+     */
+    getPublishedEvents(): PublishedEvent[];
+    /**
+     * Get published events by type
+     */
+    getPublishedEventsByType<T extends BaseEvent>(type: T['type']): PublishedEvent<T>[];
+    /**
+     * Get the last published event
+     */
+    getLastPublishedEvent(): PublishedEvent | undefined;
+    /**
+     * Get the last published event of a specific type
+     */
+    getLastPublishedEventByType<T extends BaseEvent>(type: T['type']): PublishedEvent<T> | undefined;
+    /**
+     * Check if an event type was published
+     */
+    wasPublished(eventType: string): boolean;
+    /**
+     * Check if an event with specific data was published
+     */
+    wasPublishedWith<T extends BaseEvent>(eventType: T['type'], predicate: (event: T) => boolean): boolean;
+    /**
+     * Get count of published events
+     */
+    getPublishedCount(eventType?: string): number;
+    /**
+     * Clear all published events (for test cleanup)
+     */
+    clearHistory(): void;
+    /**
+     * Clear all subscriptions
+     */
+    clearSubscriptions(): void;
+    /**
+     * Reset the mock (clear history and subscriptions)
+     */
+    reset(): void;
+    /**
+     * Simulate an incoming event (as if received from server)
+     */
+    simulateIncomingEvent<T extends BaseEvent>(event: T): Promise<void>;
+    private notifySubscribers;
+    private getQueueForPriority;
+    private delay;
+}
+/**
+ * Create a mock event bus for testing
+ */
+export declare function createMockEventBus(options?: MockEventBusOptions): MockEventBus;
+export {};

package/src/testing.d.ts

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

package/testing.d.ts

@@ -0,0 +1 @@
+export * from "./src/testing";