pulse-js-framework 1.7.30 → 1.7.32

package/runtime/interceptor-manager.js

@@ -0,0 +1,242 @@
+/**
+ * Pulse Framework - Interceptor Manager
+ *
+ * Shared interceptor management for HTTP, WebSocket, and GraphQL clients.
+ * Provides a generic pattern for request/response/message interception.
+ *
+ * @module runtime/interceptor-manager
+ */
+
+// ============================================================================
+// Interceptor Manager
+// ============================================================================
+
+/**
+ * Generic interceptor manager for request/response pipelines.
+ * Used by HTTP client, WebSocket client, and GraphQL client.
+ *
+ * @example
+ * // HTTP-style interceptors (fulfilled/rejected)
+ * const requestInterceptors = new InterceptorManager();
+ * const id = requestInterceptors.use(
+ *   (config) => ({ ...config, timestamp: Date.now() }),
+ *   (error) => Promise.reject(error)
+ * );
+ *
+ * // Process through interceptor chain
+ * for (const { fulfilled, rejected } of requestInterceptors) {
+ *   config = await fulfilled(config);
+ * }
+ *
+ * @example
+ * // WebSocket-style interceptors (onMessage/onError)
+ * const messageInterceptors = new InterceptorManager({
+ *   handlerKeys: ['onMessage', 'onError']
+ * });
+ * messageInterceptors.use(
+ *   (data) => ({ ...data, received: Date.now() }),
+ *   (err) => console.error('Parse error:', err)
+ * );
+ */
+class InterceptorManager {
+  #handlers = new Map();
+  #idCounter = 0;
+  #primaryKey;
+  #secondaryKey;
+
+  /**
+   * Create an interceptor manager
+   * @param {Object} [options] - Configuration options
+   * @param {string[]} [options.handlerKeys=['fulfilled', 'rejected']] - Property names for handlers
+   */
+  constructor(options = {}) {
+    const keys = options.handlerKeys || ['fulfilled', 'rejected'];
+    this.#primaryKey = keys[0];
+    this.#secondaryKey = keys[1] || null;
+  }
+
+  /**
+   * Add an interceptor to the chain
+   * @param {Function} primary - Primary handler (success/transform function)
+   * @param {Function} [secondary] - Secondary handler (error/fallback function)
+   * @returns {number} Interceptor ID for later removal
+   */
+  use(primary, secondary) {
+    const id = this.#idCounter++;
+    const handler = { [this.#primaryKey]: primary };
+    if (this.#secondaryKey) {
+      handler[this.#secondaryKey] = secondary;
+    }
+    this.#handlers.set(id, handler);
+    return id;
+  }
+
+  /**
+   * Remove an interceptor by ID
+   * @param {number} id - The interceptor ID returned from use()
+   * @returns {boolean} True if the interceptor was removed
+   */
+  eject(id) {
+    return this.#handlers.delete(id);
+  }
+
+  /**
+   * Remove all interceptors
+   */
+  clear() {
+    this.#handlers.clear();
+  }
+
+  /**
+   * Get the number of registered interceptors
+   * @returns {number}
+   */
+  get size() {
+    return this.#handlers.size;
+  }
+
+  /**
+   * Check if manager has any interceptors
+   * @returns {boolean}
+   */
+  get isEmpty() {
+    return this.#handlers.size === 0;
+  }
+
+  /**
+   * Get all handler IDs
+   * @returns {number[]}
+   */
+  get ids() {
+    return [...this.#handlers.keys()];
+  }
+
+  /**
+   * Iterate through all handlers
+   * @yields {Object} Handler object with primary and secondary functions
+   */
+  *[Symbol.iterator]() {
+    for (const handler of this.#handlers.values()) {
+      yield handler;
+    }
+  }
+
+  /**
+   * Get handlers as array (for pipeline processing)
+   * @returns {Object[]}
+   */
+  toArray() {
+    return [...this.#handlers.values()];
+  }
+
+  /**
+   * Run a value through all interceptors (async pipeline)
+   * Executes each interceptor's primary handler in sequence.
+   * If any handler throws, the secondary handler is called if available.
+   *
+   * @param {*} value - Initial value to process
+   * @returns {Promise<*>} Processed value after all interceptors
+   */
+  async run(value) {
+    let result = value;
+    for (const handler of this.#handlers.values()) {
+      try {
+        const fn = handler[this.#primaryKey];
+        if (typeof fn === 'function') {
+          result = await fn(result);
+        }
+      } catch (error) {
+        const errorFn = handler[this.#secondaryKey];
+        if (typeof errorFn === 'function') {
+          result = await errorFn(error);
+        } else {
+          throw error;
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Run a value through all interceptors (sync pipeline)
+   * @param {*} value - Initial value to process
+   * @returns {*} Processed value after all interceptors
+   */
+  runSync(value) {
+    let result = value;
+    for (const handler of this.#handlers.values()) {
+      try {
+        const fn = handler[this.#primaryKey];
+        if (typeof fn === 'function') {
+          result = fn(result);
+        }
+      } catch (error) {
+        const errorFn = handler[this.#secondaryKey];
+        if (typeof errorFn === 'function') {
+          result = errorFn(error);
+        } else {
+          throw error;
+        }
+      }
+    }
+    return result;
+  }
+}
+
+// ============================================================================
+// Specialized Interceptor Managers
+// ============================================================================
+
+/**
+ * Message interceptor manager pre-configured for WebSocket-style interception.
+ * Uses 'onMessage' and 'onError' as handler property names.
+ *
+ * @example
+ * const manager = new MessageInterceptorManager();
+ * manager.use(
+ *   (data) => ({ ...data, timestamp: Date.now() }),
+ *   (err) => console.error('Error:', err)
+ * );
+ *
+ * for (const { onMessage, onError } of manager) {
+ *   data = onMessage(data);
+ * }
+ */
+class MessageInterceptorManager extends InterceptorManager {
+  constructor() {
+    super({ handlerKeys: ['onMessage', 'onError'] });
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create an interceptor manager for HTTP-style request/response interception
+ * @returns {InterceptorManager}
+ */
+function createRequestInterceptors() {
+  return new InterceptorManager({ handlerKeys: ['fulfilled', 'rejected'] });
+}
+
+/**
+ * Create an interceptor manager for WebSocket-style message interception
+ * @returns {InterceptorManager}
+ */
+function createMessageInterceptors() {
+  return new InterceptorManager({ handlerKeys: ['onMessage', 'onError'] });
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export {
+  InterceptorManager,
+  MessageInterceptorManager,
+  createRequestInterceptors,
+  createMessageInterceptors
+};
+
+export default InterceptorManager;

package/runtime/router.js

@@ -18,6 +18,7 @@ import { el } from './dom.js';
 import { loggers } from './logger.js';
 import { createVersionedAsync } from './async.js';
 import { Errors } from './errors.js';
+import { LRUCache } from './lru-cache.js';
 
 const log = loggers.router;
 
@@ -516,7 +517,9 @@ export function createRouter(options = {}) {
     mode = 'history', // 'history' or 'hash'
     base = '',
     scrollBehavior = null, // Function to control scroll restoration
-    middleware: initialMiddleware = [] // Middleware functions
+    middleware: initialMiddleware = [], // Middleware functions
+    persistScroll = false, // Persist scroll positions to sessionStorage
+    persistScrollKey = 'pulse-router-scroll' // Storage key for scroll persistence
   } = options;
 
   // Middleware array (mutable for dynamic registration)
@@ -534,8 +537,47 @@ export function createRouter(options = {}) {
   // Route error handler (configurable)
   let onRouteError = options.onRouteError || null;
 
-  // Scroll positions for history
-  const scrollPositions = new Map();
+  // Scroll positions for history (LRU cache to prevent memory leaks)
+  // Keeps last 100 scroll positions - enough for typical navigation patterns
+  const scrollPositions = new LRUCache(100);
+
+  // Restore scroll positions from sessionStorage if persistence is enabled
+  if (persistScroll && typeof sessionStorage !== 'undefined') {
+    try {
+      const stored = sessionStorage.getItem(persistScrollKey);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        // Restore up to 100 most recent positions
+        const entries = Object.entries(parsed).slice(-100);
+        for (const [path, pos] of entries) {
+          if (pos && typeof pos.x === 'number' && typeof pos.y === 'number') {
+            scrollPositions.set(path, pos);
+          }
+        }
+        log.debug(`Restored ${entries.length} scroll positions from sessionStorage`);
+      }
+    } catch (err) {
+      log.warn('Failed to restore scroll positions from sessionStorage:', err.message);
+    }
+  }
+
+  /**
+   * Persist scroll positions to sessionStorage
+   */
+  function persistScrollPositions() {
+    if (!persistScroll || typeof sessionStorage === 'undefined') return;
+
+    try {
+      const data = {};
+      for (const [path, pos] of scrollPositions.entries()) {
+        data[path] = pos;
+      }
+      sessionStorage.setItem(persistScrollKey, JSON.stringify(data));
+    } catch (err) {
+      // SessionStorage may be full or disabled
+      log.warn('Failed to persist scroll positions:', err.message);
+    }
+  }
 
   // Route trie for O(path length) lookups
   const routeTrie = new RouteTrie();
@@ -694,6 +736,7 @@ export function createRouter(options = {}) {
         x: window.scrollX,
         y: window.scrollY
       });
+      persistScrollPositions();
     }
 
     // Update URL
@@ -720,25 +763,47 @@ export function createRouter(options = {}) {
    */
   function handleScroll(to, from, savedPosition) {
     if (scrollBehavior) {
-      const position = scrollBehavior(to, from, savedPosition);
-      if (position) {
-        if (position.selector) {
+      let position;
+      try {
+        position = scrollBehavior(to, from, savedPosition);
+      } catch (err) {
+        loggers.router.warn(`scrollBehavior threw an error: ${err.message}`);
+        // Fall back to default behavior
+        window.scrollTo(0, 0);
+        return;
+      }
+
+      // Validate position is a valid object
+      if (position && typeof position === 'object') {
+        if (typeof position.selector === 'string' && position.selector) {
           // Scroll to element
-          const el = document.querySelector(position.selector);
-          if (el) {
-            el.scrollIntoView({ behavior: position.behavior || 'auto' });
+          try {
+            const el = document.querySelector(position.selector);
+            if (el) {
+              const behavior = position.behavior === 'smooth' || position.behavior === 'auto'
+                ? position.behavior
+                : 'auto';
+              el.scrollIntoView({ behavior });
+            }
+          } catch (err) {
+            loggers.router.warn(`Invalid selector in scrollBehavior: ${position.selector}`);
           }
         } else if (typeof position.x === 'number' || typeof position.y === 'number') {
-          window.scrollTo({
-            left: position.x || 0,
-            top: position.y || 0,
-            behavior: position.behavior || 'auto'
-          });
+          const x = typeof position.x === 'number' && isFinite(position.x) ? position.x : 0;
+          const y = typeof position.y === 'number' && isFinite(position.y) ? position.y : 0;
+          const behavior = position.behavior === 'smooth' || position.behavior === 'auto'
+            ? position.behavior
+            : 'auto';
+          window.scrollTo({ left: x, top: y, behavior });
         }
+        // If position is object but no valid selector/x/y, do nothing (intentional no-scroll)
       }
+      // If position is falsy (null/undefined/false), do nothing (intentional no-scroll)
     } else if (savedPosition) {
       // Default: restore saved position
-      window.scrollTo(savedPosition.x, savedPosition.y);
+      const x = typeof savedPosition.x === 'number' && isFinite(savedPosition.x) ? savedPosition.x : 0;
+      const y = typeof savedPosition.y === 'number' && isFinite(savedPosition.y) ? savedPosition.y : 0;
+      window.scrollTo(x, y);
     } else {
       // Default: scroll to top
       window.scrollTo(0, 0);

package/runtime/utils.js

@@ -6,6 +6,7 @@
  */
 
 import { createLogger } from './logger.js';
+import { sanitizeHtml } from './security.js';
 
 const log = createLogger('Security');
 
@@ -98,10 +99,7 @@ export function dangerouslySetInnerHTML(element, html, options = {}) {
   const { sanitize = false, ...sanitizeOptions } = options;
 
   if (sanitize) {
-    // Import sanitizeHtml from security module
-    import('./security.js').then(({ sanitizeHtml }) => {
-      element.innerHTML = sanitizeHtml(html, sanitizeOptions);
-    });
+    element.innerHTML = sanitizeHtml(html, sanitizeOptions);
   } else {
     element.innerHTML = html;
   }
@@ -610,6 +608,117 @@ export function throttle(fn, interval) {
   return throttled;
 }
 
+// ============================================================================
+// Window Event Helpers
+// ============================================================================
+
+/**
+ * Check if running in a browser environment with window object
+ * @returns {boolean}
+ */
+export function isBrowser() {
+  return typeof window !== 'undefined';
+}
+
+/**
+ * Add a window event listener with automatic cleanup via onCleanup.
+ * Safe to call in SSR - does nothing if window is not available.
+ *
+ * @param {string} event - Event name ('focus', 'online', 'offline', etc.)
+ * @param {Function} handler - Event handler function
+ * @param {Function} onCleanup - Cleanup registration function from pulse.js
+ * @param {Object} [options] - addEventListener options
+ * @returns {Function|null} Cleanup function, or null if not in browser
+ *
+ * @example
+ * // In an effect or hook
+ * import { onCleanup } from './pulse.js';
+ * import { onWindowEvent } from './utils.js';
+ *
+ * effect(() => {
+ *   onWindowEvent('focus', () => refetch(), onCleanup);
+ *   onWindowEvent('online', () => reconnect(), onCleanup);
+ * });
+ */
+export function onWindowEvent(event, handler, onCleanup, options) {
+  if (!isBrowser()) return null;
+
+  window.addEventListener(event, handler, options);
+  const cleanup = () => window.removeEventListener(event, handler, options);
+
+  if (typeof onCleanup === 'function') {
+    onCleanup(cleanup);
+  }
+
+  return cleanup;
+}
+
+/**
+ * Add focus event listener for refetch-on-focus patterns.
+ * Common pattern in data fetching hooks.
+ *
+ * @param {Function} handler - Handler to call on window focus
+ * @param {Function} onCleanup - Cleanup registration function
+ * @returns {Function|null} Cleanup function
+ */
+export function onWindowFocus(handler, onCleanup) {
+  return onWindowEvent('focus', handler, onCleanup);
+}
+
+/**
+ * Add online event listener for refetch-on-reconnect patterns.
+ * Common pattern in data fetching hooks.
+ *
+ * @param {Function} handler - Handler to call when going online
+ * @param {Function} onCleanup - Cleanup registration function
+ * @returns {Function|null} Cleanup function
+ */
+export function onWindowOnline(handler, onCleanup) {
+  return onWindowEvent('online', handler, onCleanup);
+}
+
+/**
+ * Add offline event listener.
+ *
+ * @param {Function} handler - Handler to call when going offline
+ * @param {Function} onCleanup - Cleanup registration function
+ * @returns {Function|null} Cleanup function
+ */
+export function onWindowOffline(handler, onCleanup) {
+  return onWindowEvent('offline', handler, onCleanup);
+}
+
+/**
+ * Setup both online and offline listeners at once.
+ * Useful for connection-aware features.
+ *
+ * @param {Object} handlers - Event handlers
+ * @param {Function} [handlers.onOnline] - Called when going online
+ * @param {Function} [handlers.onOffline] - Called when going offline
+ * @param {Function} onCleanup - Cleanup registration function
+ * @returns {Function|null} Combined cleanup function
+ */
+export function onNetworkChange(handlers, onCleanup) {
+  if (!isBrowser()) return null;
+
+  const cleanups = [];
+
+  if (handlers.onOnline) {
+    cleanups.push(onWindowEvent('online', handlers.onOnline, null));
+  }
+  if (handlers.onOffline) {
+    cleanups.push(onWindowEvent('offline', handlers.onOffline, null));
+  }
+
+  const cleanup = () => cleanups.forEach(fn => fn?.());
+
+  if (typeof onCleanup === 'function') {
+    onCleanup(cleanup);
+  }
+
+  return cleanup;
+}
+
 export default {
   // XSS Prevention
   escapeHtml,
@@ -626,5 +735,12 @@ export default {
   // Utilities
   deepClone,
   debounce,
-  throttle
+  throttle,
+  // Window Event Helpers
+  isBrowser,
+  onWindowEvent,
+  onWindowFocus,
+  onWindowOnline,
+  onWindowOffline,
+  onNetworkChange
 };