pulse-js-framework 1.5.1 → 1.5.3

package/runtime/lru-cache.js

@@ -15,13 +15,21 @@ export class LRUCache {
   /**
    * Create an LRU cache
    * @param {number} capacity - Maximum number of items to store
+   * @param {Object} [options] - Configuration options
+   * @param {boolean} [options.trackMetrics=false] - Enable hit/miss/eviction tracking
    */
-  constructor(capacity) {
+  constructor(capacity, options = {}) {
     if (capacity <= 0) {
       throw new Error('LRU cache capacity must be greater than 0');
     }
     this._capacity = capacity;
     this._cache = new Map();
+
+    // Metrics tracking
+    this._trackMetrics = options.trackMetrics || false;
+    this._hits = 0;
+    this._misses = 0;
+    this._evictions = 0;
   }
 
   /**
@@ -32,9 +40,12 @@ export class LRUCache {
    */
   get(key) {
     if (!this._cache.has(key)) {
+      if (this._trackMetrics) this._misses++;
       return undefined;
     }
 
+    if (this._trackMetrics) this._hits++;
+
     // Move to end (most recently used) by re-inserting
     const value = this._cache.get(key);
     this._cache.delete(key);
@@ -57,6 +68,7 @@ export class LRUCache {
       // Remove oldest (first item in Map)
       const oldest = this._cache.keys().next().value;
       this._cache.delete(oldest);
+      if (this._trackMetrics) this._evictions++;
     }
 
     this._cache.set(key, value);
@@ -136,6 +148,46 @@ export class LRUCache {
   forEach(callback) {
     this._cache.forEach((value, key) => callback(value, key, this));
   }
+
+  /**
+   * Get cache performance metrics
+   * Only available if trackMetrics option was enabled
+   * @returns {{hits: number, misses: number, evictions: number, hitRate: number, size: number, capacity: number}}
+   * @example
+   * const cache = new LRUCache(100, { trackMetrics: true });
+   * // ... use cache ...
+   * const stats = cache.getMetrics();
+   * console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+   */
+  getMetrics() {
+    const total = this._hits + this._misses;
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      evictions: this._evictions,
+      hitRate: total > 0 ? this._hits / total : 0,
+      size: this._cache.size,
+      capacity: this._capacity
+    };
+  }
+
+  /**
+   * Reset all metrics counters to zero
+   * Useful for measuring metrics over specific time periods
+   */
+  resetMetrics() {
+    this._hits = 0;
+    this._misses = 0;
+    this._evictions = 0;
+  }
+
+  /**
+   * Enable or disable metrics tracking
+   * @param {boolean} enabled - Whether to track metrics
+   */
+  setMetricsTracking(enabled) {
+    this._trackMetrics = enabled;
+  }
 }
 
 export default LRUCache;

package/runtime/pulse.js

@@ -69,6 +69,14 @@ const log = loggers.pulse;
  * @property {Map<string, Set<EffectFn>>} effectRegistry - Module ID to effects mapping for HMR
  */
 
+/**
+ * Maximum number of effect re-run iterations before aborting.
+ * Prevents infinite loops when effects trigger each other cyclically.
+ * Set to 100 to allow deep chain reactions while catching most real loops.
+ * @type {number}
+ */
+const MAX_EFFECT_ITERATIONS = 100;
+
 /**
  * Global reactive context - holds all tracking state.
  * Exported for testing purposes (use resetContext() to reset).
@@ -102,6 +110,63 @@ export function resetContext() {
   context.effectRegistry.clear();
 }
 
+/**
+ * Counter for generating unique effect IDs
+ * @type {number}
+ */
+let effectIdCounter = 0;
+
+/**
+ * Global effect error handler
+ * @type {Function|null}
+ */
+let globalEffectErrorHandler = null;
+
+/**
+ * Custom error class for effect-related errors with context information.
+ * Provides details about which effect failed, in what phase, and its dependencies.
+ */
+export class EffectError extends Error {
+  /**
+   * Create an EffectError with context information
+   * @param {string} message - Error message
+   * @param {Object} options - Error context
+   * @param {string} [options.effectId] - Effect identifier
+   * @param {string} [options.phase] - Phase when error occurred ('cleanup' | 'execution')
+   * @param {number} [options.dependencyCount] - Number of dependencies
+   * @param {Error} [options.cause] - Original error that caused this
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'EffectError';
+    this.effectId = options.effectId || null;
+    this.phase = options.phase || 'unknown';
+    this.dependencyCount = options.dependencyCount ?? 0;
+    this.cause = options.cause || null;
+  }
+}
+
+/**
+ * Set a global error handler for effect errors.
+ * The handler receives an EffectError with full context about the failure.
+ * @param {Function|null} handler - Error handler (effectError) => void, or null to clear
+ * @returns {Function|null} Previous handler (for restoration)
+ * @example
+ * // Set up global error tracking
+ * const prevHandler = onEffectError((err) => {
+ *   console.error(`Effect ${err.effectId} failed during ${err.phase}:`, err.cause);
+ *   reportToErrorService(err);
+ * });
+ *
+ * // Later, restore previous handler
+ * onEffectError(prevHandler);
+ */
+export function onEffectError(handler) {
+  const prev = globalEffectErrorHandler;
+  globalEffectErrorHandler = handler;
+  return prev;
+}
+
 /**
  * Set the current module ID for HMR effect tracking.
  * Effects created while a module ID is set will be registered for cleanup.
@@ -386,6 +451,52 @@ export class Pulse {
   }
 }
 
+/**
+ * Handle an effect error with full context information.
+ * Tries effect-specific handler, then global handler, then logs.
+ * @private
+ * @param {Error} error - The original error
+ * @param {EffectFn} effectFn - The effect that errored
+ * @param {string} phase - Phase when error occurred ('cleanup' | 'execution')
+ */
+function handleEffectError(error, effectFn, phase) {
+  const effectError = new EffectError(
+    `Effect [${effectFn.id}] error during ${phase}: ${error.message}`,
+    {
+      effectId: effectFn.id,
+      phase,
+      dependencyCount: effectFn.dependencies?.size ?? 0,
+      cause: error
+    }
+  );
+
+  // Try effect-specific handler first
+  if (effectFn.onError) {
+    try {
+      effectFn.onError(effectError);
+      return;
+    } catch (handlerError) {
+      log.error('Effect onError handler threw:', handlerError);
+    }
+  }
+
+  // Try global handler
+  if (globalEffectErrorHandler) {
+    try {
+      globalEffectErrorHandler(effectError);
+      return;
+    } catch (handlerError) {
+      log.error('Global effect error handler threw:', handlerError);
+    }
+  }
+
+  // Default: log with context
+  log.error(`[${effectError.effectId}] ${effectError.message}`, {
+    phase: effectError.phase,
+    dependencies: effectError.dependencyCount
+  });
+}
+
 /**
  * Run a single effect safely
  * @private
@@ -398,7 +509,7 @@ function runEffect(effectFn) {
   try {
     effectFn.run();
   } catch (error) {
-    log.error('Effect error:', error);
+    handleEffectError(error, effectFn, 'execution');
   }
 }
 
@@ -412,10 +523,9 @@ function flushEffects() {
 
   context.isRunningEffects = true;
   let iterations = 0;
-  const maxIterations = 100; // Prevent infinite loops
 
   try {
-    while (context.pendingEffects.size > 0 && iterations < maxIterations) {
+    while (context.pendingEffects.size > 0 && iterations < MAX_EFFECT_ITERATIONS) {
       iterations++;
       const effects = [...context.pendingEffects];
       context.pendingEffects.clear();
@@ -425,8 +535,8 @@ function flushEffects() {
       }
     }
 
-    if (iterations >= maxIterations) {
-      log.warn('Maximum effect iterations reached. Possible infinite loop.');
+    if (iterations >= MAX_EFFECT_ITERATIONS) {
+      log.warn(`Maximum effect iterations (${MAX_EFFECT_ITERATIONS}) reached. Possible infinite loop.`);
       context.pendingEffects.clear();
     }
   } finally {
@@ -483,6 +593,8 @@ export function computed(fn, options = {}) {
 
     // Track which pulses this depends on
     let trackedDeps = new Set();
+    // Track subscription cleanup functions to prevent memory leaks
+    let subscriptionCleanups = [];
 
     p.get = function() {
       if (dirty) {
@@ -500,18 +612,21 @@ export function computed(fn, options = {}) {
           dirty = false;
 
           // Cleanup old subscriptions
-          for (const dep of trackedDeps) {
-            dep._unsubscribe(markDirty);
+          for (const unsubscribe of subscriptionCleanups) {
+            unsubscribe();
           }
+          subscriptionCleanups = [];
+          trackedDeps.clear();
 
           // Set up new subscriptions
           trackedDeps = tempEffect.dependencies;
           for (const dep of trackedDeps) {
-            dep.subscribe(() => {
+            const unsubscribe = dep.subscribe(() => {
               dirty = true;
               // Notify our own subscribers
               p._triggerNotify();
             });
+            subscriptionCleanups.push(unsubscribe);
           }
 
           p._init(cachedValue);
@@ -529,7 +644,14 @@ export function computed(fn, options = {}) {
       return cachedValue;
     };
 
-    const markDirty = { run: () => { dirty = true; }, dependencies: new Set(), cleanups: [] };
+    // Cleanup function for lazy computed
+    cleanup = () => {
+      for (const unsubscribe of subscriptionCleanups) {
+        unsubscribe();
+      }
+      subscriptionCleanups = [];
+      trackedDeps.clear();
+    };
   } else {
     // Eager computed - updates immediately when dependencies change
     cleanup = effect(() => {
@@ -568,9 +690,16 @@ export function computed(fn, options = {}) {
   return p;
 }
 
+/**
+ * @typedef {Object} EffectOptions
+ * @property {string} [id] - Custom effect identifier for debugging
+ * @property {function(EffectError): void} [onError] - Error handler for this effect
+ */
+
 /**
  * Create an effect that runs when its dependencies change
  * @param {function(): void|function(): void} fn - Effect function, may return a cleanup function
+ * @param {EffectOptions} [options={}] - Effect configuration options
  * @returns {function(): void} Dispose function to stop the effect
  * @example
  * const count = pulse(0);
@@ -588,19 +717,32 @@ export function computed(fn, options = {}) {
  *   const timer = setInterval(() => tick(), 1000);
  *   return () => clearInterval(timer); // Cleanup on re-run or dispose
  * });
+ *
+ * // With custom ID and error handler
+ * effect(() => {
+ *   // Effect logic that might fail
+ * }, {
+ *   id: 'data-sync',
+ *   onError: (err) => console.error('Data sync failed:', err.cause)
+ * });
  */
-export function effect(fn) {
+export function effect(fn, options = {}) {
+  const { id: customId, onError } = options;
+  const effectId = customId || `effect_${++effectIdCounter}`;
+
   // Capture module ID at creation time for HMR tracking
   const moduleId = context.currentModuleId;
 
   const effectFn = {
+    id: effectId,
+    onError,
     run: () => {
       // Run cleanup functions from previous run
       for (const cleanup of effectFn.cleanups) {
         try {
           cleanup();
         } catch (e) {
-          log.error('Cleanup error:', e);
+          handleEffectError(e, effectFn, 'cleanup');
         }
       }
       effectFn.cleanups = [];
@@ -618,7 +760,7 @@ export function effect(fn) {
       try {
         fn();
       } catch (error) {
-        log.error('Effect execution error:', error);
+        handleEffectError(error, effectFn, 'execution');
       } finally {
         context.currentEffect = prevEffect;
       }
@@ -645,7 +787,7 @@ export function effect(fn) {
       try {
         cleanup();
       } catch (e) {
-        log.error('Cleanup error:', e);
+        handleEffectError(e, effectFn, 'cleanup');
       }
     }
     effectFn.cleanups = [];
@@ -994,6 +1136,9 @@ export default {
   memoComputed,
   context,
   resetContext,
+  // Error handling
+  EffectError,
+  onEffectError,
   // HMR support
   setCurrentModule,
   clearCurrentModule,

package/runtime/router.js

@@ -225,8 +225,14 @@ function createMiddlewareRunner(middlewares) {
       if (aborted || redirectPath) return;
       if (index >= middlewares.length) return;
 
+      const middlewareIndex = index;
       const middleware = middlewares[index++];
-      await middleware(ctx, next);
+      try {
+        await middleware(ctx, next);
+      } catch (error) {
+        log.error(`Middleware error at index ${middlewareIndex}:`, error);
+        throw error; // Re-throw to halt navigation
+      }
     }
 
     await next();
@@ -417,23 +423,58 @@ function matchRoute(pattern, path) {
   return params;
 }
 
+// Query string validation limits
+const QUERY_LIMITS = {
+  maxTotalLength: 2048,     // 2KB max for entire query string
+  maxValueLength: 1024,     // 1KB max per individual value
+  maxParams: 50             // Maximum number of query parameters
+};
+
 /**
- * Parse query string into object
+ * Parse query string into object with validation
+ * @param {string} search - Query string (with or without leading ?)
+ * @returns {Object} Parsed query parameters
  */
 function parseQuery(search) {
-  const params = new URLSearchParams(search);
+  if (!search) return {};
+
+  // Remove leading ? if present
+  const queryStr = search.startsWith('?') ? search.slice(1) : search;
+
+  // Validate total length
+  if (queryStr.length > QUERY_LIMITS.maxTotalLength) {
+    log.warn(`Query string exceeds maximum length (${QUERY_LIMITS.maxTotalLength} chars). Truncating.`);
+  }
+
+  const params = new URLSearchParams(queryStr.slice(0, QUERY_LIMITS.maxTotalLength));
   const query = {};
+  let paramCount = 0;
+
   for (const [key, value] of params) {
+    // Check parameter count limit
+    if (paramCount >= QUERY_LIMITS.maxParams) {
+      log.warn(`Query string exceeds maximum parameters (${QUERY_LIMITS.maxParams}). Ignoring excess.`);
+      break;
+    }
+
+    // Validate and potentially truncate value length
+    let safeValue = value;
+    if (value.length > QUERY_LIMITS.maxValueLength) {
+      log.warn(`Query parameter "${key}" exceeds maximum length. Truncating.`);
+      safeValue = value.slice(0, QUERY_LIMITS.maxValueLength);
+    }
+
     if (key in query) {
       // Multiple values for same key
       if (Array.isArray(query[key])) {
-        query[key].push(value);
+        query[key].push(safeValue);
       } else {
-        query[key] = [query[key], value];
+        query[key] = [query[key], safeValue];
       }
     } else {
-      query[key] = value;
+      query[key] = safeValue;
     }
+    paramCount++;
   }
   return query;
 }
@@ -460,6 +501,10 @@ export function createRouter(options = {}) {
   const currentQuery = pulse({});
   const currentMeta = pulse({});
   const isLoading = pulse(false);
+  const routeError = pulse(null);
+
+  // Route error handler (configurable)
+  let onRouteError = options.onRouteError || null;
 
   // Scroll positions for history
   const scrollPositions = new Map();
@@ -793,25 +838,65 @@ export function createRouter(options = {}) {
           router
         };
 
-        // Call handler and render result
-        const result = typeof route.handler === 'function'
-          ? route.handler(ctx)
-          : route.handler;
+        // Helper to handle errors
+        const handleError = (error) => {
+          routeError.set(error);
+          log.error('Route component error:', error);
+
+          if (onRouteError) {
+            try {
+              const errorView = onRouteError(error, ctx);
+              if (errorView instanceof Node) {
+                container.replaceChildren(errorView);
+                currentView = errorView;
+                return true;
+              }
+            } catch (handlerError) {
+              log.error('Route error handler threw:', handlerError);
+            }
+          }
+
+          const errorEl = el('div.route-error', [
+            el('h2', 'Route Error'),
+            el('p', error.message || 'Failed to load route component')
+          ]);
+          container.replaceChildren(errorEl);
+          currentView = errorEl;
+          return true;
+        };
+
+        // Call handler and render result (with error handling)
+        let result;
+        try {
+          result = typeof route.handler === 'function'
+            ? route.handler(ctx)
+            : route.handler;
+        } catch (error) {
+          handleError(error);
+          return;
+        }
 
         if (result instanceof Node) {
           container.appendChild(result);
           currentView = result;
+          routeError.set(null);
         } else if (result && typeof result.then === 'function') {
           // Async component
           isLoading.set(true);
-          result.then(component => {
-            isLoading.set(false);
-            const view = typeof component === 'function' ? component(ctx) : component;
-            if (view instanceof Node) {
-              container.appendChild(view);
-              currentView = view;
-            }
-          });
+          routeError.set(null);
+          result
+            .then(component => {
+              isLoading.set(false);
+              const view = typeof component === 'function' ? component(ctx) : component;
+              if (view instanceof Node) {
+                container.appendChild(view);
+                currentView = view;
+              }
+            })
+            .catch(error => {
+              isLoading.set(false);
+              handleError(error);
+            });
         }
       }
     });
@@ -868,6 +953,17 @@ export function createRouter(options = {}) {
   /**
    * Check if a route matches the given path
    */
+  /**
+   * Check if a path matches the current route
+   * @param {string} path - Path to check
+   * @param {boolean} [exact=false] - If true, requires exact match; if false, matches prefixes
+   * @returns {boolean} True if path is active
+   * @example
+   * // Current path: /users/123
+   * router.isActive('/users');      // true (prefix match)
+   * router.isActive('/users', true); // false (not exact)
+   * router.isActive('/users/123', true); // true (exact match)
+   */
   function isActive(path, exact = false) {
     const current = currentPath.get();
     if (exact) {
@@ -877,7 +973,12 @@ export function createRouter(options = {}) {
   }
 
   /**
-   * Get all matched routes (for nested routes)
+   * Get all routes that match a given path (useful for nested routes)
+   * @param {string} path - Path to match against routes
+   * @returns {Array<{route: Object, params: Object}>} Array of matched routes with extracted params
+   * @example
+   * const matches = router.getMatchedRoutes('/admin/users/123');
+   * // Returns: [{route: adminRoute, params: {}}, {route: userRoute, params: {id: '123'}}]
    */
   function getMatchedRoutes(path) {
     const matches = [];
@@ -891,53 +992,107 @@ export function createRouter(options = {}) {
   }
 
   /**
-   * Go back in history
+   * Navigate back in browser history
+   * Equivalent to browser back button
+   * @returns {void}
+   * @example
+   * router.back(); // Go to previous page
    */
   function back() {
     window.history.back();
   }
 
   /**
-   * Go forward in history
+   * Navigate forward in browser history
+   * Equivalent to browser forward button
+   * @returns {void}
+   * @example
+   * router.forward(); // Go to next page (if available)
    */
   function forward() {
     window.history.forward();
   }
 
   /**
-   * Go to specific history entry
+   * Navigate to a specific position in browser history
+   * @param {number} delta - Number of entries to move (negative = back, positive = forward)
+   * @returns {void}
+   * @example
+   * router.go(-2); // Go back 2 pages
+   * router.go(1);  // Go forward 1 page
    */
   function go(delta) {
     window.history.go(delta);
   }
 
+  /**
+   * Set route error handler
+   * @param {function} handler - Error handler (error, ctx) => Node
+   * @returns {function} Previous handler
+   */
+  function setErrorHandler(handler) {
+    const prev = onRouteError;
+    onRouteError = handler;
+    return prev;
+  }
+
+  /**
+   * Router instance with reactive state and navigation methods.
+   *
+   * Reactive properties (use .get() to read value, auto-updates in effects):
+   * - path: Current URL path as string
+   * - route: Current matched route object or null
+   * - params: Route params object, e.g., {id: '123'}
+   * - query: Query params object, e.g., {page: '1'}
+   * - meta: Route meta data object
+   * - loading: Boolean indicating async route loading
+   * - error: Current route error or null
+   *
+   * @example
+   * // Read reactive state
+   * router.path.get();   // '/users/123'
+   * router.params.get(); // {id: '123'}
+   *
+   * // Subscribe to changes
+   * effect(() => {
+   *   console.log('Path changed:', router.path.get());
+   * });
+   *
+   * // Navigate
+   * router.navigate('/users/456');
+   * router.back();
+   */
   const router = {
-    // Reactive state (read-only)
+    // Reactive state (read-only) - use .get() to read, subscribe with effects
     path: currentPath,
     route: currentRoute,
     params: currentParams,
     query: currentQuery,
     meta: currentMeta,
     loading: isLoading,
+    error: routeError,
 
-    // Methods
+    // Navigation methods
     navigate,
     start,
     link,
     outlet,
+    back,
+    forward,
+    go,
+
+    // Guards and middleware
     use,
     beforeEach,
     beforeResolve,
     afterEach,
-    back,
-    forward,
-    go,
+    setErrorHandler,
 
     // Route inspection
     isActive,
     getMatchedRoutes,
 
-    // Utils
+    // Utility functions
     matchRoute,
     parseQuery
   };