@signaltree/events 7.3.1

package/src/core/factory.d.ts

@@ -0,0 +1,114 @@
+import { BaseEvent, EventActor, EventMetadata, EventPriority, EventVersion } from './types';
+/**
+ * Event Factory - Create events with proper structure
+ *
+ * Provides:
+ * - UUID v7 generation (time-sortable)
+ * - Correlation ID management
+ * - Event creation with defaults
+ * - Type-safe event factories
+ */
+/**
+ * Configuration for event factory
+ */
+export interface EventFactoryConfig {
+    /** Default source for events */
+    source: string;
+    /** Environment (production, staging, development) */
+    environment: string;
+    /** Default actor for system events */
+    systemActor?: EventActor;
+    /** Custom ID generator */
+    generateId?: () => string;
+    /** Custom correlation ID generator */
+    generateCorrelationId?: () => string;
+}
+/**
+ * Event factory for creating typed events
+ */
+export interface EventFactory<TEvents extends BaseEvent = BaseEvent> {
+    /**
+     * Create an event with full control
+     */
+    create<T extends TEvents>(type: T['type'], data: T['data'], options?: CreateEventOptions): T;
+    /**
+     * Create event with correlation from existing event
+     */
+    createFromCause<T extends TEvents>(type: T['type'], data: T['data'], cause: BaseEvent, options?: Omit<CreateEventOptions, 'correlationId' | 'causationId'>): T;
+    /**
+     * Get current correlation ID (for request context)
+     */
+    getCorrelationId(): string | undefined;
+    /**
+     * Set correlation ID for current context
+     */
+    setCorrelationId(id: string): void;
+    /**
+     * Clear correlation ID
+     */
+    clearCorrelationId(): void;
+}
+/**
+ * Options for creating an event
+ */
+export interface CreateEventOptions {
+    /** Override event ID */
+    id?: string;
+    /** Correlation ID (request trace) */
+    correlationId?: string;
+    /** Causation ID (parent event) */
+    causationId?: string;
+    /** Event actor */
+    actor?: EventActor;
+    /** Additional metadata */
+    metadata?: Partial<EventMetadata>;
+    /** Event priority */
+    priority?: EventPriority;
+    /** Aggregate info */
+    aggregate?: {
+        type: string;
+        id: string;
+    };
+    /** Schema version override */
+    version?: EventVersion;
+    /** Timestamp override (for testing/replay) */
+    timestamp?: string;
+}
+/**
+ * Generate a UUID v7 (time-sortable)
+ *
+ * UUID v7 format: timestamp (48 bits) + version (4 bits) + random (12 bits) + variant (2 bits) + random (62 bits)
+ */
+export declare function generateEventId(): string;
+/**
+ * Generate a correlation ID (also UUID v7 for traceability)
+ */
+export declare function generateCorrelationId(): string;
+/**
+ * Create a single event
+ */
+export declare function createEvent<TType extends string, TData>(type: TType, data: TData, options: CreateEventOptions & {
+    source: string;
+    environment: string;
+}): BaseEvent<TType, TData>;
+/**
+ * Create an event factory with default configuration
+ *
+ * @example
+ * ```typescript
+ * const factory = createEventFactory({
+ *   source: 'trade-service',
+ *   environment: process.env.NODE_ENV || 'development',
+ * });
+ *
+ * const event = factory.create('TradeProposalCreated', {
+ *   tradeId: '123',
+ *   initiatorId: 'user-1',
+ *   recipientId: 'user-2',
+ * }, {
+ *   actor: { id: 'user-1', type: 'user' },
+ *   priority: 'high',
+ * });
+ * ```
+ */
+export declare function createEventFactory<TEvents extends BaseEvent = BaseEvent>(config: EventFactoryConfig): EventFactory<TEvents>;

package/src/core/idempotency.d.ts

@@ -0,0 +1,209 @@
+import { BaseEvent } from './types';
+/**
+ * Idempotency Store - Prevent duplicate event processing
+ *
+ * Provides:
+ * - Idempotency key checking
+ * - In-memory implementation (for testing/development)
+ * - Redis implementation (production)
+ * - Distributed lock support
+ */
+/**
+ * Result of checking idempotency
+ */
+export interface IdempotencyCheckResult {
+    /** Whether this event has already been processed */
+    isDuplicate: boolean;
+    /** If duplicate, when was it originally processed */
+    processedAt?: Date;
+    /** If duplicate, what was the result */
+    result?: unknown;
+    /** Lock acquired for processing */
+    lockAcquired?: boolean;
+}
+/**
+ * Record of a processed event
+ */
+export interface ProcessedEventRecord {
+    /** Event ID */
+    eventId: string;
+    /** Event type */
+    eventType: string;
+    /** When processing started */
+    startedAt: Date;
+    /** When processing completed */
+    completedAt?: Date;
+    /** Processing result (success/failure) */
+    status: 'processing' | 'completed' | 'failed';
+    /** Result data (for idempotent responses) */
+    result?: unknown;
+    /** Error if failed */
+    error?: string;
+    /** Consumer/subscriber that processed the event */
+    consumer: string;
+    /** Number of processing attempts */
+    attempts: number;
+}
+/**
+ * Idempotency store interface
+ *
+ * Implementations must be atomic and handle concurrent access
+ */
+export interface IdempotencyStore {
+    /**
+     * Check if event has been processed and optionally acquire a processing lock
+     *
+     * @param event - Event to check
+     * @param consumer - Consumer/subscriber identifier
+     * @param options - Check options
+     * @returns Check result with duplicate status and optional lock
+     */
+    check(event: BaseEvent, consumer: string, options?: IdempotencyCheckOptions): Promise<IdempotencyCheckResult>;
+    /**
+     * Mark event as being processed (acquire lock)
+     *
+     * @param event - Event being processed
+     * @param consumer - Consumer/subscriber identifier
+     * @param ttlMs - Lock TTL in milliseconds
+     */
+    markProcessing(event: BaseEvent, consumer: string, ttlMs?: number): Promise<boolean>;
+    /**
+     * Mark event as successfully processed
+     *
+     * @param event - Processed event
+     * @param consumer - Consumer/subscriber identifier
+     * @param result - Optional result data for idempotent responses
+     * @param ttlMs - How long to keep the record
+     */
+    markCompleted(event: BaseEvent, consumer: string, result?: unknown, ttlMs?: number): Promise<void>;
+    /**
+     * Mark event as failed
+     *
+     * @param event - Failed event
+     * @param consumer - Consumer/subscriber identifier
+     * @param error - Error information
+     */
+    markFailed(event: BaseEvent, consumer: string, error: unknown): Promise<void>;
+    /**
+     * Release processing lock without marking completed
+     * (Used when you want to allow retry)
+     *
+     * @param event - Event to release
+     * @param consumer - Consumer/subscriber identifier
+     */
+    releaseLock(event: BaseEvent, consumer: string): Promise<void>;
+    /**
+     * Get processing record for an event
+     */
+    getRecord(eventId: string, consumer: string): Promise<ProcessedEventRecord | null>;
+    /**
+     * Clean up expired records (for stores that don't auto-expire)
+     */
+    cleanup?(): Promise<number>;
+}
+/**
+ * Options for idempotency check
+ */
+export interface IdempotencyCheckOptions {
+    /** Acquire a processing lock if not duplicate */
+    acquireLock?: boolean;
+    /** Lock TTL in milliseconds (default: 30000) */
+    lockTtlMs?: number;
+}
+/**
+ * Configuration for in-memory idempotency store
+ */
+export interface InMemoryIdempotencyStoreConfig {
+    /** Default TTL for records in milliseconds (default: 24 hours) */
+    defaultTtlMs?: number;
+    /** Default lock TTL in milliseconds (default: 30 seconds) */
+    defaultLockTtlMs?: number;
+    /** Maximum number of records to keep (LRU eviction) */
+    maxRecords?: number;
+    /** Cleanup interval in milliseconds (default: 60 seconds) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * In-memory idempotency store
+ *
+ * Best for:
+ * - Development and testing
+ * - Single-instance deployments
+ * - Short-lived processes
+ *
+ * NOT recommended for:
+ * - Production multi-instance deployments
+ * - Long-running processes with many events
+ */
+export declare class InMemoryIdempotencyStore implements IdempotencyStore {
+    private records;
+    private cleanupTimer?;
+    private readonly defaultTtlMs;
+    private readonly defaultLockTtlMs;
+    private readonly maxRecords;
+    constructor(config?: InMemoryIdempotencyStoreConfig);
+    private makeKey;
+    check(event: BaseEvent, consumer: string, options?: IdempotencyCheckOptions): Promise<IdempotencyCheckResult>;
+    markProcessing(event: BaseEvent, consumer: string, ttlMs?: number): Promise<boolean>;
+    markCompleted(event: BaseEvent, consumer: string, result?: unknown, ttlMs?: number): Promise<void>;
+    markFailed(event: BaseEvent, consumer: string, error: unknown): Promise<void>;
+    releaseLock(event: BaseEvent, consumer: string): Promise<void>;
+    getRecord(eventId: string, consumer: string): Promise<ProcessedEventRecord | null>;
+    cleanup(): Promise<number>;
+    /**
+     * Enforce max records limit using LRU-like eviction
+     */
+    private enforceMaxRecords;
+    /**
+     * Stop cleanup timer (for graceful shutdown)
+     */
+    dispose(): void;
+    /**
+     * Clear all records (for testing)
+     */
+    clear(): void;
+    /**
+     * Get stats (for monitoring)
+     */
+    getStats(): {
+        size: number;
+        maxRecords: number;
+    };
+}
+/**
+ * Create an in-memory idempotency store
+ *
+ * @example
+ * ```typescript
+ * const store = createInMemoryIdempotencyStore({
+ *   defaultTtlMs: 60 * 60 * 1000, // 1 hour
+ *   maxRecords: 50000,
+ * });
+ *
+ * // In your subscriber
+ * const result = await store.check(event, 'my-subscriber');
+ * if (result.isDuplicate) {
+ *   return result.result; // Return cached result
+ * }
+ *
+ * try {
+ *   const processResult = await processEvent(event);
+ *   await store.markCompleted(event, 'my-subscriber', processResult);
+ *   return processResult;
+ * } catch (error) {
+ *   await store.markFailed(event, 'my-subscriber', error);
+ *   throw error;
+ * }
+ * ```
+ */
+export declare function createInMemoryIdempotencyStore(config?: InMemoryIdempotencyStoreConfig): InMemoryIdempotencyStore;
+/**
+ * Generate an idempotency key from event
+ * Useful for custom implementations
+ */
+export declare function generateIdempotencyKey(event: BaseEvent, consumer: string): string;
+/**
+ * Generate an idempotency key from correlation ID
+ * Useful for request-level idempotency
+ */
+export declare function generateCorrelationKey(correlationId: string, operation: string): string;

package/src/core/registry.d.ts

@@ -0,0 +1,147 @@
+import { ZodTypeAny } from 'zod';
+import { BaseEvent, EventPriority } from './types';
+/**
+ * Event Registry - Central catalog of all registered event types
+ *
+ * Provides:
+ * - Type-safe event registration
+ * - Schema lookup by event type
+ * - Validation helpers
+ * - Event catalog for documentation
+ */
+/**
+ * Configuration for a registered event
+ */
+export interface RegisteredEvent<T extends ZodTypeAny = ZodTypeAny> {
+    /** Event type string */
+    type: string;
+    /** Zod schema for validation */
+    schema: T;
+    /** Default priority for this event type */
+    priority: EventPriority;
+    /** Human-readable description */
+    description?: string;
+    /** Event category for grouping */
+    category?: string;
+    /** Whether this event is deprecated */
+    deprecated?: boolean;
+    /** Deprecation message if deprecated */
+    deprecationMessage?: string;
+}
+/**
+ * Event registry configuration
+ */
+export interface EventRegistryConfig {
+    /** Strict mode - throw on unknown events */
+    strict?: boolean;
+    /** Log warnings for deprecated events */
+    warnOnDeprecated?: boolean;
+}
+/**
+ * Event catalog entry for documentation
+ */
+export interface EventCatalogEntry {
+    type: string;
+    category?: string;
+    priority: EventPriority;
+    description?: string;
+    deprecated: boolean;
+}
+/**
+ * Full event catalog
+ */
+export type EventCatalog = EventCatalogEntry[];
+/**
+ * Event Registry class - manages all registered event types
+ *
+ * @example
+ * ```typescript
+ * const registry = createEventRegistry();
+ *
+ * // Register events
+ * registry.register({
+ *   type: 'TradeProposalCreated',
+ *   schema: TradeProposalCreatedSchema,
+ *   priority: 'high',
+ *   description: 'Emitted when a user proposes a trade',
+ *   category: 'trade',
+ * });
+ *
+ * // Validate events
+ * const validated = registry.validate(rawEvent);
+ *
+ * // Get schema for event type
+ * const schema = registry.getSchema('TradeProposalCreated');
+ * ```
+ */
+export declare class EventRegistry {
+    private readonly events;
+    private readonly config;
+    constructor(config?: EventRegistryConfig);
+    /**
+     * Register an event type with its schema
+     */
+    register<T extends ZodTypeAny>(event: RegisteredEvent<T>): this;
+    /**
+     * Register multiple events at once
+     */
+    registerMany(events: RegisteredEvent[]): this;
+    /**
+     * Get schema for an event type
+     */
+    getSchema(type: string): ZodTypeAny | undefined;
+    /**
+     * Get registered event info
+     */
+    getEvent(type: string): RegisteredEvent | undefined;
+    /**
+     * Check if event type is registered
+     */
+    has(type: string): boolean;
+    /**
+     * Get default priority for event type
+     */
+    getPriority(type: string): EventPriority;
+    /**
+     * Validate an event against its registered schema
+     *
+     * @throws Error if event type is unknown (in strict mode) or validation fails
+     */
+    validate<T extends BaseEvent = BaseEvent>(event: unknown): T;
+    /**
+     * Check if event is valid without throwing
+     */
+    isValid(event: unknown): boolean;
+    /**
+     * Get all registered event types
+     */
+    getAllTypes(): string[];
+    /**
+     * Get all registered events
+     */
+    getAll(): RegisteredEvent[];
+    /**
+     * Get events by category
+     */
+    getByCategory(category: string): RegisteredEvent[];
+    /**
+     * Get event catalog for documentation
+     */
+    getCatalog(): EventCatalog;
+    /**
+     * Export registry as JSON schema (for external tools)
+     */
+    toJSONSchema(): Record<string, unknown>;
+}
+/**
+ * Create a new event registry
+ */
+export declare function createEventRegistry(config?: EventRegistryConfig): EventRegistry;
+/**
+ * Get schema for an event type from a registry
+ */
+export declare function getEventSchema(registry: EventRegistry, type: string): ZodTypeAny | undefined;
+/**
+ * Get all registered event types from a registry
+ */
+export declare function getAllEventTypes(registry: EventRegistry): string[];

package/src/core/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Core event types - framework-agnostic definitions
+ */
+/**
+ * Event priority levels for queue routing and SLA management
+ */
+export type EventPriority = 'critical' | 'high' | 'normal' | 'low' | 'bulk';
+/**
+ * Priority configuration with SLA targets
+ */
+export declare const EVENT_PRIORITIES: Record<EventPriority, {
+    sla: number;
+    weight: number;
+}>;
+/**
+ * Event schema version for evolution tracking
+ */
+export interface EventVersion {
+    major: number;
+    minor: number;
+}
+export declare const DEFAULT_EVENT_VERSION: EventVersion;
+/**
+ * Actor who triggered the event
+ */
+export interface EventActor {
+    /** User, system, or admin ID */
+    id: string;
+    /** Type of actor */
+    type: 'user' | 'system' | 'admin' | 'webhook';
+    /** Optional display name for audit */
+    name?: string;
+}
+/**
+ * Event metadata for tracing, audit, and debugging
+ */
+export interface EventMetadata {
+    /** Service/module that emitted the event */
+    source: string;
+    /** Environment (production, staging, development) */
+    environment: string;
+    /** Client IP address (for audit) */
+    ip?: string;
+    /** User agent string (for analytics) */
+    userAgent?: string;
+    /** Additional context */
+    [key: string]: unknown;
+}
+/**
+ * Base event interface - all events must extend this
+ *
+ * @example
+ * ```typescript
+ * interface TradeProposalCreated extends BaseEvent {
+ *   type: 'TradeProposalCreated';
+ *   data: {
+ *     tradeId: string;
+ *     initiatorId: string;
+ *     recipientId: string;
+ *   };
+ * }
+ * ```
+ */
+export interface BaseEvent<TType extends string = string, TData = unknown> {
+    /**
+     * Unique event ID (UUID v7 recommended - time-sortable)
+     */
+    id: string;
+    /**
+     * Event type in PascalCase (e.g., 'TradeProposalCreated')
+     * Must be past tense - events are facts that happened
+     */
+    type: TType;
+    /**
+     * Schema version for event evolution
+     */
+    version: EventVersion;
+    /**
+     * When the event occurred (ISO 8601)
+     */
+    timestamp: string;
+    /**
+     * Request/trace ID for distributed tracing
+     * All events from the same user action share this ID
+     */
+    correlationId: string;
+    /**
+     * ID of the event that caused this event (for event chains)
+     */
+    causationId?: string;
+    /**
+     * Who/what triggered this event
+     */
+    actor: EventActor;
+    /**
+     * Event metadata for tracing and audit
+     */
+    metadata: EventMetadata;
+    /**
+     * Event-specific payload
+     */
+    data: TData;
+    /**
+     * Priority for queue routing
+     * @default 'normal'
+     */
+    priority?: EventPriority;
+    /**
+     * Aggregate information for event sourcing
+     */
+    aggregate?: {
+        type: string;
+        id: string;
+    };
+}
+/**
+ * Type helper to extract event data type
+ */
+export type EventData<T extends BaseEvent> = T['data'];
+/**
+ * Type helper to extract event type string
+ */
+export type EventType<T extends BaseEvent> = T['type'];
+/**
+ * Union type of all registered events (to be extended by apps)
+ */
+export type AnyEvent = BaseEvent<string, unknown>;