pulse-js-framework 1.4.7 → 1.4.9

package/runtime/router.js

@@ -10,11 +10,328 @@
  * - Per-route and global guards
  * - Scroll restoration
  * - Lazy-loaded routes
+ * - Middleware support
  */
 
 import { pulse, effect, batch } from './pulse.js';
 import { el } from './dom.js';
 
+/**
+ * Lazy load helper for route components
+ * Wraps a dynamic import to provide loading states and error handling
+ *
+ * @param {function} importFn - Dynamic import function () => import('./Component.js')
+ * @param {Object} options - Lazy loading options
+ * @param {function} options.loading - Loading component function
+ * @param {function} options.error - Error component function
+ * @param {number} options.timeout - Timeout in ms (default: 10000)
+ * @param {number} options.delay - Delay before showing loading (default: 200)
+ * @returns {function} Lazy route handler
+ *
+ * @example
+ * const routes = {
+ *   '/dashboard': lazy(() => import('./Dashboard.js')),
+ *   '/settings': lazy(() => import('./Settings.js'), {
+ *     loading: () => el('div.spinner', 'Loading...'),
+ *     error: (err) => el('div.error', `Failed to load: ${err.message}`),
+ *     timeout: 5000
+ *   })
+ * };
+ */
+export function lazy(importFn, options = {}) {
+  const {
+    loading: LoadingComponent = null,
+    error: ErrorComponent = null,
+    timeout = 10000,
+    delay = 200
+  } = options;
+
+  // Cache for loaded component
+  let cachedComponent = null;
+  let loadPromise = null;
+
+  return function lazyHandler(ctx) {
+    // Return cached component if already loaded
+    if (cachedComponent) {
+      return typeof cachedComponent === 'function'
+        ? cachedComponent(ctx)
+        : cachedComponent.default
+          ? cachedComponent.default(ctx)
+          : cachedComponent.render
+            ? cachedComponent.render(ctx)
+            : cachedComponent;
+    }
+
+    // Create container for async loading
+    const container = el('div.lazy-route');
+    let loadingTimer = null;
+    let timeoutTimer = null;
+
+    // Start loading if not already
+    if (!loadPromise) {
+      loadPromise = importFn();
+    }
+
+    // Delay showing loading state to avoid flash
+    if (LoadingComponent && delay > 0) {
+      loadingTimer = setTimeout(() => {
+        if (!cachedComponent) {
+          container.replaceChildren(LoadingComponent());
+        }
+      }, delay);
+    } else if (LoadingComponent) {
+      container.replaceChildren(LoadingComponent());
+    }
+
+    // Set timeout for loading
+    const timeoutPromise = timeout > 0
+      ? new Promise((_, reject) => {
+          timeoutTimer = setTimeout(() => {
+            reject(new Error(`Lazy load timeout after ${timeout}ms`));
+          }, timeout);
+        })
+      : null;
+
+    // Race between load and timeout
+    const loadWithTimeout = timeoutPromise
+      ? Promise.race([loadPromise, timeoutPromise])
+      : loadPromise;
+
+    loadWithTimeout
+      .then(module => {
+        clearTimeout(loadingTimer);
+        clearTimeout(timeoutTimer);
+
+        // Cache the component
+        cachedComponent = module;
+
+        // Get the component from module
+        const Component = module.default || module;
+        const result = typeof Component === 'function'
+          ? Component(ctx)
+          : Component.render
+            ? Component.render(ctx)
+            : Component;
+
+        // Replace loading with actual component
+        if (result instanceof Node) {
+          container.replaceChildren(result);
+        }
+      })
+      .catch(err => {
+        clearTimeout(loadingTimer);
+        clearTimeout(timeoutTimer);
+        loadPromise = null; // Allow retry
+
+        if (ErrorComponent) {
+          container.replaceChildren(ErrorComponent(err));
+        } else {
+          console.error('Lazy load error:', err);
+          container.replaceChildren(
+            el('div.lazy-error', `Failed to load component: ${err.message}`)
+          );
+        }
+      });
+
+    return container;
+  };
+}
+
+/**
+ * Preload a lazy component without rendering
+ * Useful for prefetching on hover or when likely to navigate
+ *
+ * @param {function} lazyHandler - Lazy handler created with lazy()
+ * @returns {Promise} Resolves when component is loaded
+ *
+ * @example
+ * const DashboardLazy = lazy(() => import('./Dashboard.js'));
+ * // Preload on link hover
+ * link.addEventListener('mouseenter', () => preload(DashboardLazy));
+ */
+export function preload(lazyHandler) {
+  // Trigger the lazy handler with a dummy context to start loading
+  // The result is discarded, but the component will be cached
+  return new Promise(resolve => {
+    const result = lazyHandler({});
+    if (result instanceof Promise) {
+      result.then(resolve);
+    } else {
+      // Already loaded
+      resolve(result);
+    }
+  });
+}
+
+/**
+ * Middleware context passed to each middleware function
+ * @typedef {Object} MiddlewareContext
+ * @property {NavigationTarget} to - Target route
+ * @property {NavigationTarget} from - Source route
+ * @property {Object} meta - Shared metadata between middlewares
+ * @property {function} redirect - Redirect to another path
+ * @property {function} abort - Abort navigation
+ */
+
+/**
+ * Create a middleware runner for the router
+ * Middlewares are executed in order, each can modify context or abort navigation
+ *
+ * @param {Array<function>} middlewares - Array of middleware functions
+ * @returns {function} Runner function
+ *
+ * @example
+ * const authMiddleware = async (ctx, next) => {
+ *   if (ctx.to.meta.requiresAuth && !isAuthenticated()) {
+ *     return ctx.redirect('/login');
+ *   }
+ *   await next();
+ * };
+ *
+ * const loggerMiddleware = async (ctx, next) => {
+ *   console.log('Navigating to:', ctx.to.path);
+ *   const start = Date.now();
+ *   await next();
+ *   console.log('Navigation took:', Date.now() - start, 'ms');
+ * };
+ *
+ * const router = createRouter({
+ *   routes,
+ *   middleware: [loggerMiddleware, authMiddleware]
+ * });
+ */
+function createMiddlewareRunner(middlewares) {
+  return async function runMiddleware(context) {
+    let index = 0;
+    let aborted = false;
+    let redirectPath = null;
+
+    // Create enhanced context with redirect and abort
+    const ctx = {
+      ...context,
+      meta: {},
+      redirect: (path) => {
+        redirectPath = path;
+      },
+      abort: () => {
+        aborted = true;
+      }
+    };
+
+    async function next() {
+      if (aborted || redirectPath) return;
+      if (index >= middlewares.length) return;
+
+      const middleware = middlewares[index++];
+      await middleware(ctx, next);
+    }
+
+    await next();
+
+    return {
+      aborted,
+      redirectPath,
+      meta: ctx.meta
+    };
+  };
+}
+
+/**
+ * Radix Trie for efficient route matching
+ * Provides O(path length) lookup instead of O(routes count)
+ */
+class RouteTrie {
+  constructor() {
+    this.root = { children: new Map(), route: null, paramName: null, isWildcard: false };
+  }
+
+  /**
+   * Insert a route into the trie
+   */
+  insert(pattern, route) {
+    const segments = pattern === '/' ? [''] : pattern.split('/').filter(Boolean);
+    let node = this.root;
+
+    for (const segment of segments) {
+      let key;
+      let paramName = null;
+      let isWildcard = false;
+
+      if (segment.startsWith(':')) {
+        // Dynamic segment - :param
+        key = ':';
+        paramName = segment.slice(1);
+      } else if (segment.startsWith('*')) {
+        // Wildcard segment - *path
+        key = '*';
+        paramName = segment.slice(1) || 'wildcard';
+        isWildcard = true;
+      } else {
+        // Static segment
+        key = segment;
+      }
+
+      if (!node.children.has(key)) {
+        node.children.set(key, {
+          children: new Map(),
+          route: null,
+          paramName,
+          isWildcard
+        });
+      }
+      node = node.children.get(key);
+    }
+
+    node.route = route;
+  }
+
+  /**
+   * Find a matching route for a path
+   */
+  find(path) {
+    const segments = path === '/' ? [''] : path.split('/').filter(Boolean);
+    return this._findRecursive(this.root, segments, 0, {});
+  }
+
+  _findRecursive(node, segments, index, params) {
+    // End of path
+    if (index === segments.length) {
+      if (node.route) {
+        return { route: node.route, params };
+      }
+      return null;
+    }
+
+    const segment = segments[index];
+
+    // Try static match first (most specific)
+    if (node.children.has(segment)) {
+      const result = this._findRecursive(node.children.get(segment), segments, index + 1, params);
+      if (result) return result;
+    }
+
+    // Try dynamic param match
+    if (node.children.has(':')) {
+      const paramNode = node.children.get(':');
+      const newParams = { ...params, [paramNode.paramName]: decodeURIComponent(segment) };
+      const result = this._findRecursive(paramNode, segments, index + 1, newParams);
+      if (result) return result;
+    }
+
+    // Try wildcard match (catches all remaining segments)
+    if (node.children.has('*')) {
+      const wildcardNode = node.children.get('*');
+      const remaining = segments.slice(index).map(decodeURIComponent).join('/');
+      return {
+        route: wildcardNode.route,
+        params: { ...params, [wildcardNode.paramName]: remaining }
+      };
+    }
+
+    return null;
+  }
+}
+
 /**
  * Parse a route pattern into a regex and extract param names
  * Supports: /users/:id, /posts/:id/comments, /files/*path, * (catch-all)
@@ -126,9 +443,13 @@ export function createRouter(options = {}) {
     routes = {},
     mode = 'history', // 'history' or 'hash'
     base = '',
-    scrollBehavior = null // Function to control scroll restoration
+    scrollBehavior = null, // Function to control scroll restoration
+    middleware: initialMiddleware = [] // Middleware functions
   } = options;
 
+  // Middleware array (mutable for dynamic registration)
+  const middleware = [...initialMiddleware];
+
   // Reactive state
   const currentPath = pulse(getPath());
   const currentRoute = pulse(null);
@@ -140,6 +461,9 @@ export function createRouter(options = {}) {
   // Scroll positions for history
   const scrollPositions = new Map();
 
+  // Route trie for O(path length) lookups
+  const routeTrie = new RouteTrie();
+
   // Compile routes (supports nested routes)
   const compiledRoutes = [];
 
@@ -148,11 +472,16 @@ export function createRouter(options = {}) {
       const normalized = normalizeRoute(pattern, config);
       const fullPattern = parentPath + pattern;
 
-      compiledRoutes.push({
+      const route = {
         ...normalized,
         pattern: fullPattern,
         ...parsePattern(fullPattern)
-      });
+      };
+
+      compiledRoutes.push(route);
+
+      // Insert into trie for fast lookup
+      routeTrie.insert(fullPattern, route);
 
       // Compile children (nested routes)
       if (normalized.children) {
@@ -183,15 +512,22 @@ export function createRouter(options = {}) {
   }
 
   /**
-   * Find matching route
+   * Find matching route using trie for O(path length) lookup
    */
   function findRoute(path) {
+    // Use trie for efficient lookup
+    const result = routeTrie.find(path);
+    if (result) {
+      return result;
+    }
+
+    // Fallback to catch-all route if exists
     for (const route of compiledRoutes) {
-      const params = matchRoute(route.pattern, path);
-      if (params !== null) {
-        return { route, params };
+      if (route.pattern === '*') {
+        return { route, params: {} };
       }
     }
+
     return null;
   }
 
@@ -234,6 +570,20 @@ export function createRouter(options = {}) {
       meta: match?.route?.meta || {}
     };
 
+    // Run middleware if configured
+    if (middleware.length > 0) {
+      const runMiddleware = createMiddlewareRunner(middleware);
+      const middlewareResult = await runMiddleware({ to, from });
+      if (middlewareResult.aborted) {
+        return false;
+      }
+      if (middlewareResult.redirectPath) {
+        return navigate(middlewareResult.redirectPath, { replace: true });
+      }
+      // Merge middleware meta into route meta
+      Object.assign(to.meta, middlewareResult.meta);
+    }
+
     // Run global beforeEach hooks
     for (const hook of beforeHooks) {
       const result = await hook(to, from);
@@ -427,7 +777,7 @@ export function createRouter(options = {}) {
       // Cleanup previous view
       if (cleanup) cleanup();
       if (currentView) {
-        container.innerHTML = '';
+        container.replaceChildren();
       }
 
       if (route && route.handler) {
@@ -466,6 +816,19 @@ export function createRouter(options = {}) {
     return container;
   }
 
+  /**
+   * Add middleware dynamically
+   * @param {function} middlewareFn - Middleware function (ctx, next) => {}
+   * @returns {function} Unregister function
+   */
+  function use(middlewareFn) {
+    middleware.push(middlewareFn);
+    return () => {
+      const index = middleware.indexOf(middlewareFn);
+      if (index > -1) middleware.splice(index, 1);
+    };
+  }
+
   /**
    * Add navigation guard
    */
@@ -559,6 +922,7 @@ export function createRouter(options = {}) {
     start,
     link,
     outlet,
+    use,
     beforeEach,
     beforeResolve,
     afterEach,
@@ -591,6 +955,8 @@ export function simpleRouter(routes, target = '#app') {
 export default {
   createRouter,
   simpleRouter,
+  lazy,
+  preload,
   matchRoute,
   parseQuery
 };

package/types/hmr.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Pulse Framework - HMR (Hot Module Replacement) Type Definitions
+ * @module pulse-js-framework/runtime/hmr
+ */
+
+import { Pulse, PulseOptions } from './pulse';
+
+/**
+ * HMR Context interface for state preservation and effect cleanup
+ */
+export interface HMRContext {
+  /**
+   * Persistent data storage across HMR updates.
+   * Values stored here survive module reloads.
+   */
+  data: Record<string, unknown>;
+
+  /**
+   * Create a pulse with state preservation across HMR updates.
+   * If a value exists from a previous module load, it's restored.
+   *
+   * @param key - Unique key for this pulse within the module
+   * @param initialValue - Initial value (used on first load only)
+   * @param options - Pulse options (equals function, etc.)
+   * @returns A pulse instance with preserved state
+   *
+   * @example
+   * const count = hmr.preservePulse('count', 0);
+   * const todos = hmr.preservePulse('todos', [], { equals: deepEquals });
+   */
+  preservePulse<T>(key: string, initialValue: T, options?: PulseOptions<T>): Pulse<T>;
+
+  /**
+   * Execute code with module tracking enabled.
+   * Effects created within this callback will be registered
+   * for automatic cleanup during HMR.
+   *
+   * @param callback - Code to execute with tracking
+   * @returns The return value of the callback
+   *
+   * @example
+   * hmr.setup(() => {
+   *   effect(() => {
+   *     document.title = `Count: ${count.get()}`;
+   *   });
+   * });
+   */
+  setup<T>(callback: () => T): T;
+
+  /**
+   * Register a callback to run when the module accepts an HMR update.
+   * Call without arguments to auto-accept updates.
+   *
+   * @param callback - Optional callback for custom handling
+   *
+   * @example
+   * hmr.accept(); // Auto-accept
+   * hmr.accept(() => console.log('Module updated!'));
+   */
+  accept(callback?: () => void): void;
+
+  /**
+   * Register a callback to run before the module is replaced.
+   * Use this for custom cleanup logic.
+   *
+   * @param callback - Cleanup callback
+   *
+   * @example
+   * hmr.dispose(() => {
+   *   socket.close();
+   *   clearInterval(timer);
+   * });
+   */
+  dispose(callback: () => void): void;
+}
+
+/**
+ * Create an HMR context for a module.
+ * Provides utilities for state preservation and effect cleanup during HMR.
+ *
+ * In production or non-HMR environments, returns a no-op context
+ * that works normally but without HMR-specific behavior.
+ *
+ * @param moduleId - The module identifier (typically import.meta.url)
+ * @returns HMR context with preservation utilities
+ *
+ * @example
+ * import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+ *
+ * const hmr = createHMRContext(import.meta.url);
+ *
+ * // Preserve state across HMR
+ * const todos = hmr.preservePulse('todos', []);
+ * const filter = hmr.preservePulse('filter', 'all');
+ *
+ * // Setup effects with automatic cleanup
+ * hmr.setup(() => {
+ *   effect(() => {
+ *     document.title = `${todos.get().length} todos`;
+ *   });
+ * });
+ *
+ * // Accept HMR updates
+ * hmr.accept();
+ */
+export function createHMRContext(moduleId: string): HMRContext;
+
+declare const hmr: {
+  createHMRContext: typeof createHMRContext;
+};
+
+export default hmr;

package/types/index.d.ts

@@ -90,8 +90,15 @@ export {
   LinkOptions,
   MatchedRoute,
   Router,
+  MiddlewareContext,
+  MiddlewareFn,
+  LazyOptions,
+  LazyRouteHandler,
+  RouteContext,
   createRouter,
-  simpleRouter
+  simpleRouter,
+  lazy,
+  preload
 } from './router';
 
 // Store
@@ -137,3 +144,20 @@ export {
   logger,
   loggers
 } from './logger';
+
+// HMR (Hot Module Replacement)
+export {
+  HMRContext,
+  createHMRContext
+} from './hmr';
+
+// Source Maps (Compiler)
+export {
+  Position,
+  Mapping,
+  SourceMapV3,
+  OriginalPosition,
+  SourceMapGenerator,
+  SourceMapConsumer,
+  encodeVLQ
+} from './sourcemap';