@signaltree/events 7.3.1

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@signaltree/events",
+  "version": "7.3.1",
+  "description": "Event-driven architecture infrastructure for SignalTree - event bus, subscribers, validation, and real-time sync",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.esm.js",
+  "module": "./index.esm.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.esm.js",
+      "types": "./index.d.ts"
+    },
+    "./nestjs": {
+      "import": "./nestjs.esm.js",
+      "types": "./nestjs.d.ts"
+    },
+    "./angular": {
+      "import": "./angular.esm.js",
+      "types": "./angular.d.ts"
+    },
+    "./testing": {
+      "import": "./testing.esm.js",
+      "types": "./testing.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0",
+    "@angular/core": "^18.0.0 || ^19.0.0 || ^20.0.0",
+    "rxjs": "^7.0.0",
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "bullmq": "^5.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
+    },
+    "@signaltree/core": {
+      "optional": true
+    },
+    "socket.io-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@angular/core": "^20.0.0",
+    "@signaltree/core": "workspace:*",
+    "bullmq": "^5.0.0",
+    "ioredis": "^5.0.0",
+    "socket.io-client": "^4.0.0",
+    "rxjs": "^7.8.0",
+    "reflect-metadata": "^0.2.0",
+    "zod": "^3.24.0",
+    "vitest": "^3.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.esm.js",
+    "*.d.ts",
+    "src/**/*.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "signaltree",
+    "events",
+    "event-driven",
+    "event-bus",
+    "cqrs",
+    "bullmq",
+    "nestjs",
+    "angular",
+    "websocket",
+    "real-time"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JBorgia/signaltree.git",
+    "directory": "packages/events"
+  },
+  "bugs": {
+    "url": "https://github.com/JBorgia/signaltree/issues"
+  },
+  "homepage": "https://github.com/JBorgia/signaltree/tree/main/packages/events#readme"
+}

package/src/angular/handlers.d.ts

@@ -0,0 +1,132 @@
+import { BaseEvent } from '../core/types';
+/**
+ * Event Handlers - Utilities for handling events in Angular
+ *
+ * Provides:
+ * - Type-safe event handlers
+ * - Handler composition
+ * - Store integration helpers
+ */
+/**
+ * Event handler function type
+ */
+export type EventHandler<T extends BaseEvent = BaseEvent> = (event: T) => void | Promise<void>;
+/**
+ * Typed event handler with metadata
+ */
+export interface TypedEventHandler<T extends BaseEvent = BaseEvent> {
+    /** Event type this handler processes */
+    eventType: T['type'];
+    /** Handler function */
+    handle: EventHandler<T>;
+    /** Optional priority (lower = higher priority) */
+    priority?: number;
+}
+/**
+ * Create a simple event handler
+ *
+ * @example
+ * ```typescript
+ * const handler = createEventHandler<TradeProposalCreated>(event => {
+ *   store.$.trades.entities.upsertOne(event.data);
+ * });
+ * ```
+ */
+export declare function createEventHandler<T extends BaseEvent>(handler: EventHandler<T>): EventHandler<T>;
+/**
+ * Create a typed event handler with metadata
+ *
+ * @example
+ * ```typescript
+ * const handler = createTypedHandler('TradeProposalCreated', {
+ *   handle: (event) => {
+ *     store.$.trades.entities.upsertOne(event.data);
+ *   },
+ *   priority: 1,
+ * });
+ * ```
+ */
+export declare function createTypedHandler<T extends BaseEvent>(eventType: T['type'], options: {
+    handle: EventHandler<T>;
+    priority?: number;
+}): TypedEventHandler<T>;
+/**
+ * Create a handler registry for managing multiple handlers
+ *
+ * @example
+ * ```typescript
+ * const registry = createHandlerRegistry();
+ *
+ * registry.register('TradeProposalCreated', (event) => {
+ *   store.$.trades.entities.upsertOne(event.data);
+ * });
+ *
+ * registry.register('TradeAccepted', (event) => {
+ *   store.$.trades.entities.update(event.data.tradeId, { status: 'accepted' });
+ * });
+ *
+ * // In WebSocket service
+ * protected onEventReceived(event: BaseEvent): void {
+ *   registry.dispatch(event);
+ * }
+ * ```
+ */
+export declare function createHandlerRegistry(): {
+    register: <T extends BaseEvent>(eventType: T['type'], handler: EventHandler<T>) => void;
+    unregister: (eventType: string, handler?: EventHandler) => void;
+    dispatch: (event: BaseEvent) => Promise<void>;
+    getHandlers: (eventType: string) => EventHandler[];
+    clear: () => void;
+};
+/**
+ * Compose multiple handlers into one
+ *
+ * @example
+ * ```typescript
+ * const composedHandler = composeHandlers(
+ *   logHandler,
+ *   metricsHandler,
+ *   storeHandler,
+ * );
+ * ```
+ */
+export declare function composeHandlers<T extends BaseEvent>(...handlers: EventHandler<T>[]): EventHandler<T>;
+/**
+ * Create a conditional handler that only runs if predicate is true
+ *
+ * @example
+ * ```typescript
+ * const handler = conditionalHandler(
+ *   (event) => event.data.status === 'pending',
+ *   (event) => processPendingTrade(event),
+ * );
+ * ```
+ */
+export declare function conditionalHandler<T extends BaseEvent>(predicate: (event: T) => boolean, handler: EventHandler<T>): EventHandler<T>;
+/**
+ * Create a handler that debounces rapid events
+ *
+ * @example
+ * ```typescript
+ * const handler = debouncedHandler(
+ *   (event) => updateUI(event),
+ *   100, // 100ms debounce
+ * );
+ * ```
+ */
+export declare function debouncedHandler<T extends BaseEvent>(handler: EventHandler<T>, delayMs: number): EventHandler<T>;
+/**
+ * Create a handler that batches events and processes them together
+ *
+ * @example
+ * ```typescript
+ * const handler = batchedHandler(
+ *   (events) => {
+ *     store.$.trades.entities.upsertMany(events.map(e => e.data));
+ *   },
+ *   50, // Process batch every 50ms
+ *   100, // Or when batch reaches 100 events
+ * );
+ * ```
+ */
+export declare function batchedHandler<T extends BaseEvent>(handler: (events: T[]) => void | Promise<void>, flushIntervalMs: number, maxBatchSize?: number): EventHandler<T>;

package/src/angular/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @signaltree/events/angular
+ *
+ * Angular integration for real-time event synchronization.
+ * Provides WebSocket service base for SignalTree integration.
+ */
+export { WebSocketService } from './websocket.service';
+export type { WebSocketConfig, ConnectionState, WebSocketMessage, } from './websocket.service';
+export { OptimisticUpdateManager } from './optimistic-updates';
+export type { OptimisticUpdate, UpdateResult } from './optimistic-updates';
+export { createEventHandler, createTypedHandler } from './handlers';
+export type { EventHandler, TypedEventHandler } from './handlers';

package/src/angular/optimistic-updates.d.ts

@@ -0,0 +1,117 @@
+import { Signal } from '@angular/core';
+/**
+ * Optimistic Update Manager - Handle optimistic UI updates with rollback
+ *
+ * Provides:
+ * - Track pending updates
+ * - Automatic rollback on failure
+ * - Correlation with server events
+ */
+/**
+ * Pending optimistic update
+ */
+export interface OptimisticUpdate<T = unknown> {
+    /** Unique ID for tracking */
+    id: string;
+    /** Correlation ID to match with server response */
+    correlationId: string;
+    /** Type of update */
+    type: string;
+    /** Optimistic data applied to UI */
+    data: T;
+    /** Previous data for rollback */
+    previousData: T;
+    /** When the update was applied */
+    appliedAt: Date;
+    /** Timeout for automatic rollback (ms) */
+    timeoutMs: number;
+    /** Rollback function */
+    rollback: () => void;
+}
+/**
+ * Result of an optimistic update
+ */
+export interface UpdateResult {
+    success: boolean;
+    correlationId: string;
+    error?: Error;
+}
+/**
+ * Optimistic Update Manager
+ *
+ * Tracks optimistic updates and handles confirmation/rollback.
+ *
+ * @example
+ * ```typescript
+ * const manager = new OptimisticUpdateManager();
+ *
+ * // Apply optimistic update
+ * manager.apply({
+ *   id: 'update-1',
+ *   correlationId: 'corr-123',
+ *   type: 'UpdateTradeStatus',
+ *   data: { status: 'accepted' },
+ *   previousData: { status: 'pending' },
+ *   timeoutMs: 5000,
+ *   rollback: () => store.$.trade.status.set('pending'),
+ * });
+ *
+ * // When server confirms
+ * manager.confirm('corr-123');
+ *
+ * // Or when server rejects
+ * manager.rollback('corr-123', new Error('Server rejected'));
+ * ```
+ */
+export declare class OptimisticUpdateManager {
+    private readonly _updates;
+    private timeouts;
+    /**
+     * Number of pending updates
+     */
+    readonly pendingCount: Signal<number>;
+    /**
+     * Whether there are any pending updates
+     */
+    readonly hasPending: Signal<boolean>;
+    /**
+     * Get all pending updates
+     */
+    readonly pending: Signal<OptimisticUpdate[]>;
+    /**
+     * Apply an optimistic update
+     */
+    apply<T>(update: OptimisticUpdate<T>): void;
+    /**
+     * Confirm an optimistic update (server accepted)
+     */
+    confirm(correlationId: string): boolean;
+    /**
+     * Rollback an optimistic update (server rejected or timeout)
+     */
+    rollback(correlationId: string, error?: Error): boolean;
+    /**
+     * Rollback all pending updates
+     */
+    rollbackAll(error?: Error): number;
+    /**
+     * Get update by correlation ID
+     */
+    get(correlationId: string): OptimisticUpdate | undefined;
+    /**
+     * Check if an update is pending
+     */
+    isPending(correlationId: string): boolean;
+    /**
+     * Clear all updates without rollback (use with caution)
+     */
+    clear(): void;
+    /**
+     * Dispose the manager
+     */
+    dispose(): void;
+}
+/**
+ * Create an optimistic update manager instance
+ */
+export declare function createOptimisticUpdateManager(): OptimisticUpdateManager;

package/src/angular/websocket.service.d.ts

@@ -0,0 +1,158 @@
+import { OnDestroy, Signal } from '@angular/core';
+import { Observable } from 'rxjs';
+import { BaseEvent } from '../core/types';
+/**
+ * WebSocket Service - Base class for real-time event synchronization
+ *
+ * Provides:
+ * - WebSocket connection management
+ * - Automatic reconnection with exponential backoff
+ * - Presence tracking
+ * - SignalTree integration
+ */
+/**
+ * WebSocket connection states
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * WebSocket configuration
+ */
+export interface WebSocketConfig {
+    /** WebSocket URL */
+    url: string;
+    /** Reconnection settings */
+    reconnect?: {
+        enabled: boolean;
+        initialDelayMs: number;
+        maxDelayMs: number;
+        maxAttempts: number;
+    };
+    /** Heartbeat settings */
+    heartbeat?: {
+        enabled: boolean;
+        intervalMs: number;
+        timeoutMs: number;
+    };
+    /** Auth token getter */
+    getAuthToken?: () => string | null | Promise<string | null>;
+    /** Protocols */
+    protocols?: string[];
+}
+/**
+ * WebSocket message wrapper
+ */
+export interface WebSocketMessage<T = unknown> {
+    type: 'event' | 'ack' | 'error' | 'ping' | 'pong' | 'subscribe' | 'unsubscribe';
+    payload?: T;
+    eventType?: string;
+    correlationId?: string;
+    timestamp?: string;
+}
+/**
+ * Default configuration
+ */
+declare const DEFAULT_CONFIG: Required<Pick<WebSocketConfig, 'reconnect' | 'heartbeat'>>;
+/**
+ * Base WebSocket service for real-time event synchronization
+ *
+ * Extend this class in your application and wire it to your SignalTree store.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class AppWebSocketService extends WebSocketService {
+ *   private readonly store = inject(AppStore);
+ *
+ *   constructor() {
+ *     super({
+ *       url: environment.wsUrl,
+ *       getAuthToken: () => this.store.$.session.token(),
+ *     });
+ *
+ *     // Subscribe to events
+ *     this.onEvent<TradeProposalCreated>('TradeProposalCreated').subscribe(event => {
+ *       this.store.$.trades.entities.upsertOne(event.data);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class WebSocketService implements OnDestroy {
+    private readonly destroyRef;
+    private readonly _connectionState;
+    private readonly _lastError;
+    private readonly _reconnectAttempts;
+    private readonly _lastMessageTime;
+    readonly connectionState: Signal<ConnectionState>;
+    readonly lastError: Signal<Error | null>;
+    readonly isConnected: Signal<boolean>;
+    readonly isReconnecting: Signal<boolean>;
+    private socket$?;
+    private readonly messageSubject;
+    private readonly subscribedEvents;
+    private heartbeatInterval?;
+    private reconnectTimer?;
+    protected readonly config: WebSocketConfig & typeof DEFAULT_CONFIG;
+    constructor(config: WebSocketConfig);
+    /**
+     * Connect to WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Send a message
+     */
+    send(message: WebSocketMessage): void;
+    /**
+     * Subscribe to a specific event type
+     *
+     * @example
+     * ```typescript
+     * this.onEvent<TradeProposalCreated>('TradeProposalCreated').subscribe(event => {
+     *   console.log('Trade created:', event);
+     * });
+     * ```
+     */
+    onEvent<T extends BaseEvent>(eventType: T['type']): Observable<T>;
+    /**
+     * Unsubscribe from an event type
+     */
+    offEvent(eventType: string): void;
+    /**
+     * Get all messages (for debugging/logging)
+     */
+    get messages$(): Observable<WebSocketMessage>;
+    /**
+     * Wait for connection to be established
+     */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    ngOnDestroy(): void;
+    /**
+     * Called when connection is established
+     * Override in subclass to perform initialization
+     */
+    protected onConnected(): void;
+    /**
+     * Called when connection is lost
+     * Override in subclass to handle cleanup
+     */
+    protected onDisconnected(): void;
+    /**
+     * Called when an event is received
+     * Override in subclass to dispatch to store
+     */
+    protected onEventReceived(_event: BaseEvent): void;
+    private handleOpen;
+    private handleClose;
+    private handleMessage;
+    private handleError;
+    private handleComplete;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+export {};

package/src/angular.d.ts

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

package/src/core/error-classification.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Error Classification - Determine retry behavior for errors
+ *
+ * Provides:
+ * - Retryable vs non-retryable error classification
+ * - Error categories (transient, permanent, poison)
+ * - Retry configuration per error type
+ * - Custom error classifiers
+ */
+/**
+ * Error classification result
+ */
+export type ErrorClassification = 'transient' | 'permanent' | 'poison' | 'unknown';
+/**
+ * Retry configuration for classified errors
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Initial delay in milliseconds */
+    initialDelayMs: number;
+    /** Maximum delay in milliseconds */
+    maxDelayMs: number;
+    /** Backoff multiplier */
+    backoffMultiplier: number;
+    /** Jitter factor (0-1) to prevent thundering herd */
+    jitter: number;
+}
+/**
+ * Error classification result with retry config
+ */
+export interface ClassificationResult {
+    classification: ErrorClassification;
+    retryConfig?: RetryConfig;
+    sendToDlq: boolean;
+    reason: string;
+}
+/**
+ * Default retry configurations by classification
+ */
+export declare const DEFAULT_RETRY_CONFIGS: Record<ErrorClassification, RetryConfig>;
+/**
+ * Custom error classifier function
+ */
+export type ErrorClassifier = (error: unknown) => ErrorClassification | null;
+/**
+ * Error classifier configuration
+ */
+export interface ErrorClassifierConfig {
+    /** Custom classifiers (checked first) */
+    customClassifiers?: ErrorClassifier[];
+    /** Override default retry configs */
+    retryConfigs?: Partial<Record<ErrorClassification, Partial<RetryConfig>>>;
+    /** Default classification for unknown errors */
+    defaultClassification?: ErrorClassification;
+}
+/**
+ * Create an error classifier
+ *
+ * @example
+ * ```typescript
+ * const classifier = createErrorClassifier({
+ *   customClassifiers: [
+ *     (error) => {
+ *       if (error instanceof MyCustomTransientError) return 'transient';
+ *       return null; // Let default classification handle it
+ *     }
+ *   ],
+ *   retryConfigs: {
+ *     transient: { maxAttempts: 10 }, // Override max attempts
+ *   },
+ * });
+ *
+ * const result = classifier.classify(error);
+ * if (result.sendToDlq) {
+ *   await dlqService.send(event, error, result.reason);
+ * }
+ * ```
+ */
+export declare function createErrorClassifier(config?: ErrorClassifierConfig): {
+    classify: (error: unknown) => ClassificationResult;
+    isRetryable: (error: unknown) => boolean;
+    calculateDelay: (attempt: number, config: RetryConfig) => number;
+};
+/**
+ * Pre-configured error classifier instance
+ */
+export declare const defaultErrorClassifier: {
+    classify: (error: unknown) => ClassificationResult;
+    isRetryable: (error: unknown) => boolean;
+    calculateDelay: (attempt: number, config: RetryConfig) => number;
+};
+/**
+ * Quick helper to check if error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Quick helper to classify error
+ */
+export declare function classifyError(error: unknown): ClassificationResult;