@signaltree/events 7.6.1 → 8.0.0

package/README.md

@@ -8,6 +8,18 @@ Event-driven architecture infrastructure for SignalTree applications. Provides a
 npm install @signaltree/events zod
 ```
 
+## Module Format (ESM-only)
+
+`@signaltree/events` ships as **pure ESM**.
+
+- ✅ Works in ESM environments (modern bundlers, Vite, Angular, Node ESM)
+- ❌ **Does not support** CommonJS `require()` (you'll get `ERR_REQUIRE_ESM`)
+
+If you're using the NestJS entry (`@signaltree/events/nestjs`) from Node, make sure your backend runs in ESM mode, for example:
+
+- `package.json`: set `"type": "module"`
+- `tsconfig.json`: set `"module": "NodeNext"` and `"moduleResolution": "NodeNext"`
+
 ## Subpath Exports
 
 The package provides four entry points for different use cases:

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@signaltree/events",
-  "version": "7.6.1",
+  "version": "8.0.0",
   "description": "Event-driven architecture infrastructure for SignalTree - event bus, subscribers, validation, and real-time sync",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "module": "./index.esm.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./src/index.d.ts",
   "typesVersions": {
     "*": {
@@ -25,25 +25,21 @@
     ".": {
       "types": "./src/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
       "default": "./dist/index.js"
     },
     "./nestjs": {
       "types": "./src/nestjs/index.d.ts",
       "import": "./dist/nestjs/index.js",
-      "require": "./dist/nestjs/index.cjs",
       "default": "./dist/nestjs/index.js"
     },
     "./angular": {
       "types": "./src/angular/index.d.ts",
       "import": "./dist/angular/index.js",
-      "require": "./dist/angular/index.cjs",
       "default": "./dist/angular/index.js"
     },
     "./testing": {
       "types": "./src/testing/index.d.ts",
       "import": "./dist/testing/index.js",
-      "require": "./dist/testing/index.cjs",
       "default": "./dist/testing/index.js"
     },
     "./package.json": "./package.json"
@@ -103,7 +99,6 @@
   },
   "files": [
     "dist/**/*.js",
-    "dist/**/*.cjs",
     "src/**/*.d.ts",
     "README.md"
   ],
@@ -128,4 +123,4 @@
     "url": "https://github.com/JBorgia/signaltree/issues"
   },
   "homepage": "https://github.com/JBorgia/signaltree/tree/main/packages/events#readme"
-}
+}

package/dist/angular/handlers.cjs

@@ -1,38 +0,0 @@
-'use strict';
-
-/**
- * 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
-  };
-}
-
-exports.createEventHandler = createEventHandler;
-exports.createTypedHandler = createTypedHandler;

package/dist/angular/index.cjs

@@ -1,15 +0,0 @@
-'use strict';
-
-var websocket_service = require('./websocket.service.cjs');
-var optimisticUpdates = require('./optimistic-updates.cjs');
-var handlers = require('./handlers.cjs');
-
-
-
-Object.defineProperty(exports, "WebSocketService", {
-	enumerable: true,
-	get: function () { return websocket_service.WebSocketService; }
-});
-exports.OptimisticUpdateManager = optimisticUpdates.OptimisticUpdateManager;
-exports.createEventHandler = handlers.createEventHandler;
-exports.createTypedHandler = handlers.createTypedHandler;

package/dist/angular/optimistic-updates.cjs

@@ -1,161 +0,0 @@
-'use strict';
-
-var core = require('@angular/core');
-
-/**
- * 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 = core.signal(new Map());
-  timeouts = new Map();
-  /**
-   * Number of pending updates
-   */
-  pendingCount = core.computed(() => this._updates().size);
-  /**
-   * Whether there are any pending updates
-   */
-  hasPending = core.computed(() => this._updates().size > 0);
-  /**
-   * Get all pending updates
-   */
-  pending = core.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();
-  }
-}
-
-exports.OptimisticUpdateManager = OptimisticUpdateManager;

package/dist/angular/websocket.service.cjs

@@ -1,357 +0,0 @@
-'use strict';
-
-var tslib = require('tslib');
-var core = require('@angular/core');
-var rxjsInterop = require('@angular/core/rxjs-interop');
-var rxjs = require('rxjs');
-var operators = require('rxjs/operators');
-var webSocket = require('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);
- *     });
- *   }
- * }
- * ```
- */
-exports.WebSocketService = class WebSocketService {
-  destroyRef = core.inject(core.DestroyRef);
-  // Signals for reactive state
-  _connectionState = core.signal('disconnected');
-  _lastError = core.signal(null);
-  _reconnectAttempts = core.signal(0);
-  _lastMessageTime = core.signal(null);
-  // Public readonly signals
-  connectionState = this._connectionState.asReadonly();
-  lastError = this._lastError.asReadonly();
-  isConnected = core.computed(() => this._connectionState() === 'connected');
-  isReconnecting = core.computed(() => this._connectionState() === 'reconnecting');
-  // WebSocket subject
-  socket$;
-  messageSubject = new rxjs.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.webSocket(wsConfig);
-      // Subscribe to messages
-      this.socket$.pipe(rxjsInterop.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(operators.filter(msg => msg.type === 'event' && msg.eventType === eventType), operators.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;
-    }
-  }
-};
-exports.WebSocketService = tslib.__decorate([core.Injectable(), tslib.__metadata("design:paramtypes", [Object])], exports.WebSocketService);