@signaltree/events 7.3.1

package/angular.d.ts

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

package/angular.esm.js

@@ -0,0 +1,547 @@
+import { __decorate, __metadata } from 'tslib';
+import { Injectable, inject, DestroyRef, signal, computed } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { Subject } from 'rxjs';
+import { filter, map } from 'rxjs/operators';
+import { webSocket } from 'rxjs/webSocket';
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+  reconnect: {
+    enabled: true,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+    maxAttempts: 10
+  },
+  heartbeat: {
+    enabled: true,
+    intervalMs: 30000,
+    timeoutMs: 5000
+  }
+};
+/**
+ * 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);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+let WebSocketService = class WebSocketService {
+  destroyRef = inject(DestroyRef);
+  // Signals for reactive state
+  _connectionState = signal('disconnected');
+  _lastError = signal(null);
+  _reconnectAttempts = signal(0);
+  _lastMessageTime = signal(null);
+  // Public readonly signals
+  connectionState = this._connectionState.asReadonly();
+  lastError = this._lastError.asReadonly();
+  isConnected = computed(() => this._connectionState() === 'connected');
+  isReconnecting = computed(() => this._connectionState() === 'reconnecting');
+  // WebSocket subject
+  socket$;
+  messageSubject = new Subject();
+  // Subscriptions tracking
+  subscribedEvents = new Set();
+  heartbeatInterval;
+  reconnectTimer;
+  // Config
+  config;
+  constructor(config) {
+    this.config = {
+      ...config,
+      reconnect: {
+        ...DEFAULT_CONFIG.reconnect,
+        ...config.reconnect
+      },
+      heartbeat: {
+        ...DEFAULT_CONFIG.heartbeat,
+        ...config.heartbeat
+      }
+    };
+  }
+  /**
+   * Connect to WebSocket server
+   */
+  async connect() {
+    if (this._connectionState() === 'connected' || this._connectionState() === 'connecting') {
+      return;
+    }
+    this._connectionState.set('connecting');
+    this._lastError.set(null);
+    try {
+      // Get auth token if needed
+      let url = this.config.url;
+      if (this.config.getAuthToken) {
+        const token = await this.config.getAuthToken();
+        if (token) {
+          url = `${url}${url.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}`;
+        }
+      }
+      // Create WebSocket
+      const wsConfig = {
+        url,
+        openObserver: {
+          next: () => this.handleOpen()
+        },
+        closeObserver: {
+          next: event => this.handleClose(event)
+        },
+        protocol: this.config.protocols
+      };
+      this.socket$ = webSocket(wsConfig);
+      // Subscribe to messages
+      this.socket$.pipe(takeUntilDestroyed(this.destroyRef)).subscribe({
+        next: message => this.handleMessage(message),
+        error: error => this.handleError(error),
+        complete: () => this.handleComplete()
+      });
+    } catch (error) {
+      this._connectionState.set('error');
+      this._lastError.set(error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  }
+  /**
+   * Disconnect from WebSocket server
+   */
+  disconnect() {
+    this.stopHeartbeat();
+    this.clearReconnectTimer();
+    if (this.socket$) {
+      this.socket$.complete();
+      this.socket$ = undefined;
+    }
+    this._connectionState.set('disconnected');
+    this.subscribedEvents.clear();
+  }
+  /**
+   * Send a message
+   */
+  send(message) {
+    if (!this.socket$ || this._connectionState() !== 'connected') {
+      console.warn('WebSocket not connected, message not sent:', message);
+      return;
+    }
+    this.socket$.next(message);
+  }
+  /**
+   * Subscribe to a specific event type
+   *
+   * @example
+   * ```typescript
+   * this.onEvent<TradeProposalCreated>('TradeProposalCreated').subscribe(event => {
+   *   console.log('Trade created:', event);
+   * });
+   * ```
+   */
+  onEvent(eventType) {
+    // Track subscription
+    if (!this.subscribedEvents.has(eventType)) {
+      this.subscribedEvents.add(eventType);
+      // Send subscribe message if connected
+      if (this._connectionState() === 'connected') {
+        this.send({
+          type: 'subscribe',
+          eventType
+        });
+      }
+    }
+    return this.messageSubject.pipe(filter(msg => msg.type === 'event' && msg.eventType === eventType), map(msg => msg.payload));
+  }
+  /**
+   * Unsubscribe from an event type
+   */
+  offEvent(eventType) {
+    if (this.subscribedEvents.has(eventType)) {
+      this.subscribedEvents.delete(eventType);
+      if (this._connectionState() === 'connected') {
+        this.send({
+          type: 'unsubscribe',
+          eventType
+        });
+      }
+    }
+  }
+  /**
+   * Get all messages (for debugging/logging)
+   */
+  get messages$() {
+    return this.messageSubject.asObservable();
+  }
+  /**
+   * Wait for connection to be established
+   */
+  async waitForConnection(timeoutMs = 10000) {
+    return new Promise((resolve, reject) => {
+      if (this._connectionState() === 'connected') {
+        resolve();
+        return;
+      }
+      const startTime = Date.now();
+      const checkInterval = setInterval(() => {
+        if (this._connectionState() === 'connected') {
+          clearInterval(checkInterval);
+          resolve();
+        } else if (Date.now() - startTime > timeoutMs) {
+          clearInterval(checkInterval);
+          reject(new Error('Connection timeout'));
+        }
+      }, 100);
+    });
+  }
+  ngOnDestroy() {
+    this.disconnect();
+    this.messageSubject.complete();
+  }
+  // =====================================================================
+  // Protected methods for subclass customization
+  // =====================================================================
+  /**
+   * Called when connection is established
+   * Override in subclass to perform initialization
+   */
+  onConnected() {
+    // Override in subclass
+  }
+  /**
+   * Called when connection is lost
+   * Override in subclass to handle cleanup
+   */
+  onDisconnected() {
+    // Override in subclass
+  }
+  /**
+   * Called when an event is received
+   * Override in subclass to dispatch to store
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onEventReceived(_event) {
+    // Override in subclass
+  }
+  // =====================================================================
+  // Private handlers
+  // =====================================================================
+  handleOpen() {
+    this._connectionState.set('connected');
+    this._reconnectAttempts.set(0);
+    this._lastError.set(null);
+    // Re-subscribe to events
+    for (const eventType of this.subscribedEvents) {
+      this.send({
+        type: 'subscribe',
+        eventType
+      });
+    }
+    // Start heartbeat
+    if (this.config.heartbeat.enabled) {
+      this.startHeartbeat();
+    }
+    this.onConnected();
+  }
+  handleClose(event) {
+    this.stopHeartbeat();
+    if (event.wasClean) {
+      this._connectionState.set('disconnected');
+    } else {
+      this._connectionState.set('error');
+      this._lastError.set(new Error(`Connection closed: ${event.reason || 'Unknown reason'}`));
+    }
+    this.onDisconnected();
+    // Attempt reconnection if enabled
+    if (this.config.reconnect.enabled && !event.wasClean) {
+      this.scheduleReconnect();
+    }
+  }
+  handleMessage(message) {
+    this._lastMessageTime.set(new Date());
+    this.messageSubject.next(message);
+    switch (message.type) {
+      case 'event':
+        if (message.payload) {
+          this.onEventReceived(message.payload);
+        }
+        break;
+      case 'pong':
+        // Heartbeat response received
+        break;
+      case 'error':
+        console.error('Server error:', message.payload);
+        break;
+    }
+  }
+  handleError(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    this._lastError.set(err);
+    this._connectionState.set('error');
+    console.error('WebSocket error:', err);
+    // Attempt reconnection
+    if (this.config.reconnect.enabled) {
+      this.scheduleReconnect();
+    }
+  }
+  handleComplete() {
+    this._connectionState.set('disconnected');
+    this.onDisconnected();
+  }
+  // =====================================================================
+  // Reconnection logic
+  // =====================================================================
+  scheduleReconnect() {
+    const attempts = this._reconnectAttempts();
+    const maxAttempts = this.config.reconnect.maxAttempts;
+    if (attempts >= maxAttempts) {
+      console.error(`Max reconnection attempts (${maxAttempts}) reached`);
+      this._connectionState.set('error');
+      return;
+    }
+    this._connectionState.set('reconnecting');
+    this._reconnectAttempts.set(attempts + 1);
+    // Exponential backoff
+    const delayMs = Math.min(this.config.reconnect.initialDelayMs * Math.pow(2, attempts), this.config.reconnect.maxDelayMs);
+    console.log(`Reconnecting in ${delayMs}ms (attempt ${attempts + 1}/${maxAttempts})`);
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch(error => {
+        console.error('Reconnection failed:', error);
+      });
+    }, delayMs);
+  }
+  clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = undefined;
+    }
+  }
+  // =====================================================================
+  // Heartbeat logic
+  // =====================================================================
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatInterval = setInterval(() => {
+      if (this._connectionState() === 'connected') {
+        this.send({
+          type: 'ping'
+        });
+      }
+    }, this.config.heartbeat.intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = undefined;
+    }
+  }
+};
+WebSocketService = __decorate([Injectable(), __metadata("design:paramtypes", [Object])], WebSocketService);
+
+/**
+ * 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'));
+ * ```
+ */
+class OptimisticUpdateManager {
+  _updates = signal(new Map());
+  timeouts = new Map();
+  /**
+   * Number of pending updates
+   */
+  pendingCount = computed(() => this._updates().size);
+  /**
+   * Whether there are any pending updates
+   */
+  hasPending = computed(() => this._updates().size > 0);
+  /**
+   * Get all pending updates
+   */
+  pending = computed(() => Array.from(this._updates().values()));
+  /**
+   * Apply an optimistic update
+   */
+  apply(update) {
+    // Store the update
+    this._updates.update(map => {
+      const newMap = new Map(map);
+      newMap.set(update.correlationId, update);
+      return newMap;
+    });
+    // Set timeout for automatic rollback
+    const timeout = setTimeout(() => {
+      this.rollback(update.correlationId, new Error(`Optimistic update timeout after ${update.timeoutMs}ms`));
+    }, update.timeoutMs);
+    this.timeouts.set(update.correlationId, timeout);
+  }
+  /**
+   * Confirm an optimistic update (server accepted)
+   */
+  confirm(correlationId) {
+    const update = this._updates().get(correlationId);
+    if (!update) {
+      return false;
+    }
+    // Clear timeout
+    const timeout = this.timeouts.get(correlationId);
+    if (timeout) {
+      clearTimeout(timeout);
+      this.timeouts.delete(correlationId);
+    }
+    // Remove from pending
+    this._updates.update(map => {
+      const newMap = new Map(map);
+      newMap.delete(correlationId);
+      return newMap;
+    });
+    return true;
+  }
+  /**
+   * Rollback an optimistic update (server rejected or timeout)
+   */
+  rollback(correlationId, error) {
+    const update = this._updates().get(correlationId);
+    if (!update) {
+      return false;
+    }
+    // Clear timeout
+    const timeout = this.timeouts.get(correlationId);
+    if (timeout) {
+      clearTimeout(timeout);
+      this.timeouts.delete(correlationId);
+    }
+    // Execute rollback
+    try {
+      update.rollback();
+    } catch (rollbackError) {
+      console.error('Rollback failed:', rollbackError);
+    }
+    // Remove from pending
+    this._updates.update(map => {
+      const newMap = new Map(map);
+      newMap.delete(correlationId);
+      return newMap;
+    });
+    if (error) {
+      console.warn(`Optimistic update rolled back: ${error.message}`);
+    }
+    return true;
+  }
+  /**
+   * Rollback all pending updates
+   */
+  rollbackAll(error) {
+    const updates = Array.from(this._updates().keys());
+    let count = 0;
+    for (const correlationId of updates) {
+      if (this.rollback(correlationId, error)) {
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Get update by correlation ID
+   */
+  get(correlationId) {
+    return this._updates().get(correlationId);
+  }
+  /**
+   * Check if an update is pending
+   */
+  isPending(correlationId) {
+    return this._updates().has(correlationId);
+  }
+  /**
+   * Clear all updates without rollback (use with caution)
+   */
+  clear() {
+    // Clear all timeouts
+    for (const timeout of this.timeouts.values()) {
+      clearTimeout(timeout);
+    }
+    this.timeouts.clear();
+    // Clear updates
+    this._updates.set(new Map());
+  }
+  /**
+   * Dispose the manager
+   */
+  dispose() {
+    this.clear();
+  }
+}
+
+/**
+ * Create a simple event handler
+ *
+ * @example
+ * ```typescript
+ * const handler = createEventHandler<TradeProposalCreated>(event => {
+ *   store.$.trades.entities.upsertOne(event.data);
+ * });
+ * ```
+ */
+function createEventHandler(handler) {
+  return handler;
+}
+/**
+ * Create a typed event handler with metadata
+ *
+ * @example
+ * ```typescript
+ * const handler = createTypedHandler('TradeProposalCreated', {
+ *   handle: (event) => {
+ *     store.$.trades.entities.upsertOne(event.data);
+ *   },
+ *   priority: 1,
+ * });
+ * ```
+ */
+function createTypedHandler(eventType, options) {
+  return {
+    eventType,
+    handle: options.handle,
+    priority: options.priority ?? 10
+  };
+}
+
+export { OptimisticUpdateManager, WebSocketService, createEventHandler, createTypedHandler };