pulse-js-framework 1.7.30 → 1.7.32

package/runtime/websocket.js

@@ -26,29 +26,32 @@
 
 import { pulse, computed, batch, onCleanup } from './pulse.js';
 import { createVersionedAsync } from './async.js';
-import { RuntimeError, createErrorMessage, getDocsUrl } from './errors.js';
+import { ClientError } from './errors.js';
 import { loggers } from './logger.js';
+import { MessageInterceptorManager } from './interceptor-manager.js';
 
 // ============================================================================
 // WebSocket Error Class
 // ============================================================================
 
 /**
- * WebSocket-specific error suggestions
+ * WebSocket Error with connection and reconnection context.
+ * Extends ClientError for consistent error handling patterns.
  */
-const WEBSOCKET_SUGGESTIONS = {
-  CONNECT_FAILED: 'Check the WebSocket URL and ensure the server is running. Verify CORS settings if connecting cross-origin.',
-  CLOSE: 'The connection was closed. Check close code for reason. Common codes: 1000 (normal), 1001 (going away), 1006 (abnormal).',
-  TIMEOUT: 'Connection timed out. Check network conditions or increase the timeout value.',
-  PARSE_ERROR: 'Failed to parse incoming message. Check message format matches expected type (JSON/binary).',
-  SEND_FAILED: 'Failed to send message. Connection may be closed or message exceeds size limit.',
-  RECONNECT_EXHAUSTED: 'Maximum reconnection attempts reached. Consider increasing maxRetries or checking server availability.'
-};
+export class WebSocketError extends ClientError {
+  static suggestions = {
+    CONNECT_FAILED: 'Check the WebSocket URL and ensure the server is running. Verify CORS settings if connecting cross-origin.',
+    CLOSE: 'The connection was closed. Check close code for reason. Common codes: 1000 (normal), 1001 (going away), 1006 (abnormal).',
+    TIMEOUT: 'Connection timed out. Check network conditions or increase the timeout value.',
+    PARSE_ERROR: 'Failed to parse incoming message. Check message format matches expected type (JSON/binary).',
+    SEND_FAILED: 'Failed to send message. Connection may be closed or message exceeds size limit.',
+    RECONNECT_EXHAUSTED: 'Maximum reconnection attempts reached. Consider increasing maxRetries or checking server availability.'
+  };
+
+  static errorName = 'WebSocketError';
+  static defaultCode = 'WEBSOCKET_ERROR';
+  static markerProperty = 'isWebSocketError';
 
-/**
- * WebSocket Error with connection context
- */
-export class WebSocketError extends RuntimeError {
   /**
    * @param {string} message - Error message
    * @param {Object} [options={}] - Error options
@@ -57,25 +60,21 @@ export class WebSocketError extends RuntimeError {
    * @param {number} [options.closeCode] - WebSocket close code
    * @param {string} [options.closeReason] - WebSocket close reason
    * @param {Event} [options.event] - Original event
+   * @param {number} [options.reconnectAttempt] - Current reconnection attempt number
+   * @param {number} [options.maxRetries] - Maximum reconnection retries configured
+   * @param {number} [options.nextRetryDelay] - Delay until next retry in ms
    */
   constructor(message, options = {}) {
-    const code = options.code || 'WEBSOCKET_ERROR';
-    const formattedMessage = createErrorMessage({
-      code,
-      message,
-      context: options.context,
-      suggestion: options.suggestion || WEBSOCKET_SUGGESTIONS[code]
-    });
-
-    super(formattedMessage, { code });
-
-    this.name = 'WebSocketError';
-    this.code = code;
+    super(message, options);
     this.url = options.url || null;
     this.closeCode = options.closeCode || null;
     this.closeReason = options.closeReason || null;
     this.event = options.event || null;
-    this.isWebSocketError = true;
+
+    // Reconnection context
+    this.reconnectAttempt = typeof options.reconnectAttempt === 'number' ? options.reconnectAttempt : null;
+    this.maxRetries = typeof options.maxRetries === 'number' ? options.maxRetries : null;
+    this.nextRetryDelay = typeof options.nextRetryDelay === 'number' ? options.nextRetryDelay : null;
   }
 
   /**
@@ -89,67 +88,45 @@ export class WebSocketError extends RuntimeError {
 
   isConnectFailed() { return this.code === 'CONNECT_FAILED'; }
   isClose() { return this.code === 'CLOSE'; }
-  isTimeout() { return this.code === 'TIMEOUT'; }
   isParseError() { return this.code === 'PARSE_ERROR'; }
   isSendFailed() { return this.code === 'SEND_FAILED'; }
-}
-
-// ============================================================================
-// Message Interceptor Manager
-// ============================================================================
-
-/**
- * Manages message interceptors for incoming/outgoing messages
- */
-class MessageInterceptorManager {
-  #handlers = new Map();
-  #idCounter = 0;
-
-  /**
-   * Add a message interceptor
-   * @param {Function} onMessage - Transform message data
-   * @param {Function} [onError] - Handle interceptor errors
-   * @returns {number} Interceptor ID
-   */
-  use(onMessage, onError) {
-    const id = this.#idCounter++;
-    this.#handlers.set(id, { onMessage, onError });
-    return id;
-  }
+  isReconnectExhausted() { return this.code === 'RECONNECT_EXHAUSTED'; }
 
   /**
-   * Remove an interceptor by ID
-   * @param {number} id - The interceptor ID
-   */
-  eject(id) {
-    this.#handlers.delete(id);
-  }
-
-  /**
-   * Remove all interceptors
+   * Check if this error occurred during reconnection
+   * @returns {boolean}
    */
-  clear() {
-    this.#handlers.clear();
+  isReconnecting() {
+    return this.reconnectAttempt !== null && this.reconnectAttempt > 0;
   }
 
   /**
-   * Get the number of interceptors
-   * @returns {number}
+   * Check if more reconnection attempts are available
+   * @returns {boolean}
    */
-  get size() {
-    return this.#handlers.size;
+  canRetry() {
+    if (this.maxRetries === null || this.reconnectAttempt === null) {
+      return false;
+    }
+    return this.reconnectAttempt < this.maxRetries;
   }
 
   /**
-   * Iterate through handlers
+   * Get remaining reconnection attempts
+   * @returns {number|null}
    */
-  *[Symbol.iterator]() {
-    for (const handler of this.#handlers.values()) {
-      yield handler;
+  getRemainingRetries() {
+    if (this.maxRetries === null || this.reconnectAttempt === null) {
+      return null;
     }
+    return Math.max(0, this.maxRetries - this.reconnectAttempt);
   }
 }
 
+// ============================================================================
+// Message Interceptor Factory
+// ============================================================================
+
 // ============================================================================
 // Internal Helpers
 // ============================================================================
@@ -487,10 +464,13 @@ export function createWebSocket(url, options = {}) {
 
   function handleSocketError(event, ctx) {
     ctx.ifCurrent(() => {
+      const attempt = reconnectAttempt.get();
       const wsError = new WebSocketError('WebSocket error', {
         code: 'CONNECT_FAILED',
         url,
-        event
+        event,
+        reconnectAttempt: attempt > 0 ? attempt : null,
+        maxRetries: opts.reconnect ? opts.maxRetries : null
       });
       error.set(wsError);
       eventEmitter.emit('error', wsError);
@@ -501,6 +481,12 @@ export function createWebSocket(url, options = {}) {
 
   function handleError(wsError, ctx) {
     ctx.ifCurrent(() => {
+      // Add reconnection context to error if not already present
+      if (wsError.reconnectAttempt === null && opts.reconnect) {
+        wsError.reconnectAttempt = reconnectAttempt.get();
+        wsError.maxRetries = opts.maxRetries;
+      }
+
       error.set(wsError);
       state.set('closed');
       eventEmitter.emit('error', wsError);
@@ -560,7 +546,9 @@ export function createWebSocket(url, options = {}) {
     if (opts.maxRetries > 0 && attempt >= opts.maxRetries) {
       error.set(new WebSocketError('Max reconnection attempts reached', {
         code: 'RECONNECT_EXHAUSTED',
-        url
+        url,
+        reconnectAttempt: attempt,
+        maxRetries: opts.maxRetries
       }));
       reconnecting.set(false);
       return;
@@ -864,6 +852,7 @@ export function useWebSocket(url, options = {}) {
 // Exports
 // ============================================================================
 
+// Re-export MessageInterceptorManager from shared module
 export { MessageInterceptorManager };
 
 export default {