pulse-js-framework 1.7.29 → 1.7.31

package/runtime/graphql.js

@@ -7,23 +7,15 @@ import { pulse, computed, batch, effect, onCleanup } from './pulse.js';
 import { createHttp, HttpError } from './http.js';
 import { createWebSocket, WebSocketError } from './websocket.js';
 import { createVersionedAsync } from './async.js';
-import { RuntimeError, createErrorMessage, getDocsUrl } from './errors.js';
+import { ClientError } from './errors.js';
+import { LRUCache } from './lru-cache.js';
+import { InterceptorManager } from './interceptor-manager.js';
+import { onWindowFocus, onWindowOnline } from './utils.js';
 
 // ============================================================================
 // Constants
 // ============================================================================
 
-const GRAPHQL_SUGGESTIONS = {
-  GRAPHQL_ERROR: 'Check the GraphQL errors array for specific field errors.',
-  NETWORK_ERROR: 'Verify network connectivity and GraphQL endpoint URL.',
-  PARSE_ERROR: 'The response was not valid GraphQL JSON. Check server configuration.',
-  TIMEOUT: 'Request timed out. Consider increasing timeout or optimizing query.',
-  AUTHENTICATION_ERROR: 'Authentication required. Check your credentials or token.',
-  AUTHORIZATION_ERROR: 'Insufficient permissions for this operation.',
-  VALIDATION_ERROR: 'Invalid input provided. Check variables match schema types.',
-  SUBSCRIPTION_ERROR: 'WebSocket subscription failed. Check connection status.'
-};
-
 /**
  * graphql-ws protocol message types
  * @see https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md
@@ -48,10 +40,25 @@ const MessageType = {
 // ============================================================================
 
 /**
- * Error class for GraphQL operations
- * @extends RuntimeError
+ * Error class for GraphQL operations.
+ * Extends ClientError for consistent error handling patterns.
  */
-export class GraphQLError extends RuntimeError {
+export class GraphQLError extends ClientError {
+  static suggestions = {
+    GRAPHQL_ERROR: 'Check the GraphQL errors array for specific field errors.',
+    NETWORK_ERROR: 'Verify network connectivity and GraphQL endpoint URL.',
+    PARSE_ERROR: 'The response was not valid GraphQL JSON. Check server configuration.',
+    TIMEOUT: 'Request timed out. Consider increasing timeout or optimizing query.',
+    AUTHENTICATION_ERROR: 'Authentication required. Check your credentials or token.',
+    AUTHORIZATION_ERROR: 'Insufficient permissions for this operation.',
+    VALIDATION_ERROR: 'Invalid input provided. Check variables match schema types.',
+    SUBSCRIPTION_ERROR: 'WebSocket subscription failed. Check connection status.'
+  };
+
+  static errorName = 'GraphQLError';
+  static defaultCode = 'GRAPHQL_ERROR';
+  static markerProperty = 'isGraphQLError';
+
   /**
    * @param {string} message - Error message
    * @param {Object} [options={}] - Error options
@@ -63,17 +70,7 @@ export class GraphQLError extends RuntimeError {
    * @param {Object} [options.request] - Request configuration
    */
   constructor(message, options = {}) {
-    const suggestion = GRAPHQL_SUGGESTIONS[options.code] || GRAPHQL_SUGGESTIONS.GRAPHQL_ERROR;
-    super(
-      createErrorMessage({
-        code: options.code || 'GRAPHQL_ERROR',
-        message,
-        suggestion
-      }),
-      { code: options.code || 'GRAPHQL_ERROR', suggestion }
-    );
-
-    this.name = 'GraphQLError';
+    super(message, options);
     this.errors = options.errors || [];
     this.data = options.data ?? null;
     this.extensions = options.extensions || {};
@@ -87,7 +84,7 @@ export class GraphQLError extends RuntimeError {
    * @returns {boolean}
    */
   static isGraphQLError(error) {
-    return error instanceof GraphQLError;
+    return error?.isGraphQLError === true || error instanceof GraphQLError;
   }
 
   /**
@@ -125,22 +122,6 @@ export class GraphQLError extends RuntimeError {
       this.errors.some(e => e.extensions?.code === 'BAD_USER_INPUT');
   }
 
-  /**
-   * Check if this is a network error
-   * @returns {boolean}
-   */
-  isNetworkError() {
-    return this.code === 'NETWORK_ERROR';
-  }
-
-  /**
-   * Check if this is a timeout error
-   * @returns {boolean}
-   */
-  isTimeout() {
-    return this.code === 'TIMEOUT';
-  }
-
   /**
    * Get the first error message from GraphQL errors
    * @returns {string|null}
@@ -231,60 +212,6 @@ function generateCacheKey(query, variables) {
   return `gql:${queryHash}${variablesHash ? ':' + variablesHash : ''}`;
 }
 
-// ============================================================================
-// Interceptor Manager
-// ============================================================================
-
-/**
- * Manages request/response interceptors
- */
-class InterceptorManager {
-  #handlers = new Map();
-  #nextId = 0;
-
-  /**
-   * Add an interceptor
-   * @param {Function} fulfilled - Success handler
-   * @param {Function} [rejected] - Error handler
-   * @returns {number} Interceptor ID
-   */
-  use(fulfilled, rejected) {
-    const id = this.#nextId++;
-    this.#handlers.set(id, { fulfilled, rejected });
-    return id;
-  }
-
-  /**
-   * Remove an interceptor
-   * @param {number} id - Interceptor ID
-   */
-  eject(id) {
-    this.#handlers.delete(id);
-  }
-
-  /**
-   * Clear all interceptors
-   */
-  clear() {
-    this.#handlers.clear();
-  }
-
-  /**
-   * Get handler count
-   * @returns {number}
-   */
-  get size() {
-    return this.#handlers.size;
-  }
-
-  /**
-   * Iterate over handlers
-   */
-  [Symbol.iterator]() {
-    return this.#handlers.values();
-  }
-}
-
 // ============================================================================
 // Subscription Manager
 // ============================================================================
@@ -503,7 +430,8 @@ class GraphQLClient {
   #subscriptionManager = null;
   #options;
   #inflightQueries = new Map();
-  #cache = new Map();
+  // LRU cache to prevent unbounded memory growth (default 500 entries)
+  #cache;
 
   /**
    * Request interceptors
@@ -536,12 +464,16 @@ class GraphQLClient {
       wsMaxRetries: options.wsMaxRetries ?? 5,
       cache: options.cache ?? true,
       cacheTime: options.cacheTime ?? 300000,
+      cacheMaxSize: options.cacheMaxSize ?? 500,
       staleTime: options.staleTime ?? 0,
       dedupe: options.dedupe ?? true,
       throwOnError: options.throwOnError ?? true,
       onError: options.onError
     };
 
+    // Initialize LRU cache to prevent unbounded memory growth
+    this.#cache = new LRUCache(this.#options.cacheMaxSize);
+
     // Create HTTP client for queries/mutations
     this.#http = createHttp({
       baseURL: '',
@@ -863,6 +795,7 @@ class GraphQLClient {
  * @param {number} [options.wsMaxRetries=5] - Max WebSocket reconnection attempts
  * @param {boolean} [options.cache=true] - Enable query caching
  * @param {number} [options.cacheTime=300000] - Cache TTL in ms
+ * @param {number} [options.cacheMaxSize=500] - Maximum cache entries (LRU eviction)
  * @param {number} [options.staleTime=0] - Stale threshold in ms
  * @param {boolean} [options.dedupe=true] - Deduplicate identical in-flight queries
  * @param {boolean} [options.throwOnError=true] - Throw on GraphQL errors
@@ -1047,21 +980,13 @@ export function useQuery(query, variables, options = {}) {
   }
 
   // Setup window focus listener
-  if (options.refetchOnFocus && typeof window !== 'undefined') {
-    const handleFocus = () => {
-      if (isEnabled()) executeQuery();
-    };
-    window.addEventListener('focus', handleFocus);
-    onCleanup(() => window.removeEventListener('focus', handleFocus));
+  if (options.refetchOnFocus) {
+    onWindowFocus(() => { if (isEnabled()) executeQuery(); }, onCleanup);
   }
 
   // Setup online listener
-  if (options.refetchOnReconnect && typeof window !== 'undefined') {
-    const handleOnline = () => {
-      if (isEnabled()) executeQuery();
-    };
-    window.addEventListener('online', handleOnline);
-    onCleanup(() => window.removeEventListener('online', handleOnline));
+  if (options.refetchOnReconnect) {
+    onWindowOnline(() => { if (isEnabled()) executeQuery(); }, onCleanup);
   }
 
   return {
@@ -1221,6 +1146,9 @@ export function useMutation(mutation, options = {}) {
  * @param {Function} [options.onError] - Error callback
  * @param {Function} [options.onComplete] - Called when subscription ends
  * @param {boolean} [options.shouldResubscribe=true] - Resubscribe on error
+ * @param {number} [options.retryBaseDelay=1000] - Base delay for exponential backoff (ms)
+ * @param {number} [options.retryMaxDelay=30000] - Maximum delay between retries (ms)
+ * @param {number} [options.maxRetries=Infinity] - Maximum number of retry attempts
  * @returns {Object} Subscription result with reactive state
  */
 export function useSubscription(subscription, variables, options = {}) {
@@ -1229,8 +1157,30 @@ export function useSubscription(subscription, variables, options = {}) {
   const data = pulse(null);
   const error = pulse(null);
   const status = pulse('connecting');
+  const retryCount = pulse(0);
 
   let unsubscribeFn = null;
+  let retryTimeoutId = null;
+
+  // Backoff configuration
+  const retryBaseDelay = options.retryBaseDelay ?? 1000;
+  const retryMaxDelay = options.retryMaxDelay ?? 30000;
+  const maxRetries = options.maxRetries ?? Infinity;
+
+  /**
+   * Calculate delay with exponential backoff and jitter
+   * @param {number} attempt - Current retry attempt (0-indexed)
+   * @returns {number} Delay in milliseconds
+   */
+  function calculateBackoffDelay(attempt) {
+    // Exponential backoff: baseDelay * 2^attempt
+    const exponentialDelay = retryBaseDelay * Math.pow(2, attempt);
+    // Cap at max delay
+    const cappedDelay = Math.min(exponentialDelay, retryMaxDelay);
+    // Add jitter (±25%) to prevent thundering herd
+    const jitter = cappedDelay * 0.25 * (Math.random() * 2 - 1);
+    return Math.max(0, cappedDelay + jitter);
+  }
 
   // Resolve variables
   const resolveVariables = () => {
@@ -1260,6 +1210,8 @@ export function useSubscription(subscription, variables, options = {}) {
       onData: (payload) => {
         status.set('connected');
         data.set(payload);
+        // Reset retry count on successful data
+        retryCount.set(0);
         options.onData?.(payload);
       },
       onError: (err) => {
@@ -1267,10 +1219,21 @@ export function useSubscription(subscription, variables, options = {}) {
         status.set('error');
         options.onError?.(err);
 
-        // Resubscribe on error if enabled
+        // Resubscribe on error if enabled and under max retries
         if (options.shouldResubscribe !== false) {
-          unsubscribeFn = null;
-          setTimeout(() => subscribe(), 1000);
+          const currentRetry = retryCount.peek();
+          if (currentRetry < maxRetries) {
+            unsubscribeFn = null;
+            const delay = calculateBackoffDelay(currentRetry);
+            retryCount.set(currentRetry + 1);
+            status.set('reconnecting');
+            retryTimeoutId = setTimeout(() => {
+              retryTimeoutId = null;
+              subscribe();
+            }, delay);
+          } else {
+            status.set('failed');
+          }
         }
       },
       onComplete: () => {
@@ -1285,11 +1248,17 @@ export function useSubscription(subscription, variables, options = {}) {
    * Unsubscribe
    */
   function unsubscribe() {
+    // Cancel pending retry
+    if (retryTimeoutId) {
+      clearTimeout(retryTimeoutId);
+      retryTimeoutId = null;
+    }
     if (unsubscribeFn) {
       unsubscribeFn();
       unsubscribeFn = null;
       status.set('closed');
     }
+    retryCount.set(0);
   }
 
   /**
@@ -1325,6 +1294,7 @@ export function useSubscription(subscription, variables, options = {}) {
     data,
     error,
     status,
+    retryCount,
     unsubscribe,
     resubscribe
   };

package/runtime/http.js

@@ -5,27 +5,30 @@
 
 import { pulse, computed, batch } from './pulse.js';
 import { useAsync, useResource } from './async.js';
-import { RuntimeError, createErrorMessage, getDocsUrl } from './errors.js';
+import { ClientError } from './errors.js';
+import { InterceptorManager } from './interceptor-manager.js';
 
 // ============================================================================
 // HTTP Error Class
 // ============================================================================
 
 /**
- * HTTP-specific error suggestions
+ * HTTP Error with request/response context.
+ * Extends ClientError for consistent error handling patterns.
  */
-const HTTP_SUGGESTIONS = {
-  TIMEOUT: 'Consider increasing the timeout or checking network conditions.',
-  NETWORK: 'Check internet connectivity and ensure the server is reachable.',
-  ABORT: 'Request was cancelled. This is usually intentional.',
-  HTTP_ERROR: 'Check the response status and server logs for details.',
-  PARSE_ERROR: 'The response could not be parsed. Check the Content-Type header.'
-};
+export class HttpError extends ClientError {
+  static suggestions = {
+    TIMEOUT: 'Consider increasing the timeout or checking network conditions.',
+    NETWORK: 'Check internet connectivity and ensure the server is reachable.',
+    ABORT: 'Request was cancelled. This is usually intentional.',
+    HTTP_ERROR: 'Check the response status and server logs for details.',
+    PARSE_ERROR: 'The response could not be parsed. Check the Content-Type header.'
+  };
+
+  static errorName = 'HttpError';
+  static defaultCode = 'HTTP_ERROR';
+  static markerProperty = 'isHttpError';
 
-/**
- * HTTP Error with request/response context
- */
-export class HttpError extends RuntimeError {
   /**
    * @param {string} message - Error message
    * @param {Object} [options={}] - Error options
@@ -35,50 +38,22 @@ export class HttpError extends RuntimeError {
    * @param {Object} [options.response] - The HttpResponse object
    */
   constructor(message, options = {}) {
-    const code = options.code || 'HTTP_ERROR';
-    const formattedMessage = createErrorMessage({
-      code,
-      message,
-      context: options.context,
-      suggestion: options.suggestion || HTTP_SUGGESTIONS[code]
-    });
-
-    super(formattedMessage, { code });
-
-    this.name = 'HttpError';
+    super(message, options);
     this.config = options.config || null;
-    this.code = code;
     this.request = options.request || null;
     this.response = options.response || null;
     this.status = options.response?.status || null;
-    this.isHttpError = true;
   }
 
   /**
    * Check if an error is an HttpError
    * @param {any} error - The error to check
-   * @returns {boolean} True if the error is an HttpError
+   * @returns {boolean}
    */
   static isHttpError(error) {
     return error?.isHttpError === true;
   }
 
-  /**
-   * Check if this is a timeout error
-   * @returns {boolean}
-   */
-  isTimeout() {
-    return this.code === 'TIMEOUT';
-  }
-
-  /**
-   * Check if this is a network error
-   * @returns {boolean}
-   */
-  isNetworkError() {
-    return this.code === 'NETWORK';
-  }
-
   /**
    * Check if this is an abort/cancellation error
    * @returns {boolean}
@@ -88,63 +63,6 @@ export class HttpError extends RuntimeError {
   }
 }
 
-// ============================================================================
-// Interceptor Manager
-// ============================================================================
-
-/**
- * Manages request or response interceptors
- */
-class InterceptorManager {
-  #handlers = new Map();
-  #idCounter = 0;
-
-  /**
-   * Add an interceptor
-   * @param {Function} fulfilled - Function to run on success
-   * @param {Function} [rejected] - Function to run on error
-   * @returns {number} Interceptor ID (for removal)
-   */
-  use(fulfilled, rejected) {
-    const id = this.#idCounter++;
-    this.#handlers.set(id, { fulfilled, rejected });
-    return id;
-  }
-
-  /**
-   * Remove an interceptor by ID
-   * @param {number} id - The interceptor ID
-   */
-  eject(id) {
-    this.#handlers.delete(id);
-  }
-
-  /**
-   * Remove all interceptors
-   */
-  clear() {
-    this.#handlers.clear();
-  }
-
-  /**
-   * Iterate through handlers
-   * @yields {Object} Handler with fulfilled and rejected functions
-   */
-  *[Symbol.iterator]() {
-    for (const handler of this.#handlers.values()) {
-      yield handler;
-    }
-  }
-
-  /**
-   * Get the number of interceptors
-   * @returns {number}
-   */
-  get size() {
-    return this.#handlers.size;
-  }
-}
-
 // ============================================================================
 // HTTP Client
 // ============================================================================