pulse-js-framework 1.4.8 → 1.4.9

package/compiler/transformer.js

@@ -7,9 +7,11 @@
  * - Import statement support
  * - Slot-based component composition
  * - CSS scoping with unique class prefixes
+ * - Source map generation
  */
 
 import { NodeType } from './parser.js';
+import { SourceMapGenerator } from './sourcemap.js';
 
 /** Generate a unique scope ID for CSS scoping */
 const generateScopeId = () => 'p' + Math.random().toString(36).substring(2, 8);
@@ -29,13 +31,92 @@ const STATEMENT_TOKEN_TYPES = new Set(['IF', 'FOR', 'EACH']);
 export class Transformer {
   constructor(ast, options = {}) {
     this.ast = ast;
-    this.options = { runtime: 'pulse-js-framework/runtime', minify: false, scopeStyles: true, ...options };
+    this.options = {
+      runtime: 'pulse-js-framework/runtime',
+      minify: false,
+      scopeStyles: true,
+      sourceMap: false,        // Enable source map generation
+      sourceFileName: null,    // Original .pulse file name
+      sourceContent: null,     // Original source content (for inline source maps)
+      ...options
+    };
     this.stateVars = new Set();
     this.propVars = new Set();
     this.propDefaults = new Map();
     this.actionNames = new Set();
     this.importedComponents = new Map();
     this.scopeId = this.options.scopeStyles ? generateScopeId() : null;
+
+    // Source map tracking
+    this.sourceMap = null;
+    this._currentLine = 0;
+    this._currentColumn = 0;
+
+    // Initialize source map generator if enabled
+    if (this.options.sourceMap) {
+      this.sourceMap = new SourceMapGenerator({
+        file: this.options.sourceFileName?.replace('.pulse', '.js') || 'output.js'
+      });
+      if (this.options.sourceFileName) {
+        this.sourceMap.addSource(
+          this.options.sourceFileName,
+          this.options.sourceContent
+        );
+      }
+    }
+  }
+
+  /**
+   * Add a mapping to the source map
+   * @param {Object} original - Original position {line, column} (1-based)
+   * @param {string} name - Optional identifier name
+   */
+  _addMapping(original, name = null) {
+    if (!this.sourceMap || !original) return;
+
+    this.sourceMap.addMapping({
+      generated: {
+        line: this._currentLine,
+        column: this._currentColumn
+      },
+      original: {
+        line: original.line - 1, // Convert to 0-based
+        column: original.column - 1
+      },
+      source: this.options.sourceFileName,
+      name
+    });
+  }
+
+  /**
+   * Track output position when writing code
+   * @param {string} code - Generated code
+   * @returns {string} The same code (for chaining)
+   */
+  _trackCode(code) {
+    for (const char of code) {
+      if (char === '\n') {
+        this._currentLine++;
+        this._currentColumn = 0;
+      } else {
+        this._currentColumn++;
+      }
+    }
+    return code;
+  }
+
+  /**
+   * Write code with optional source mapping
+   * @param {string} code - Code to write
+   * @param {Object} original - Original position {line, column}
+   * @param {string} name - Optional identifier name
+   * @returns {string} The code
+   */
+  _emit(code, original = null, name = null) {
+    if (original) {
+      this._addMapping(original, name);
+    }
+    return this._trackCode(code);
   }
 
   /**
@@ -100,7 +181,32 @@ export class Transformer {
     // Component export
     parts.push(this.generateExport());
 
-    return parts.filter(Boolean).join('\n\n');
+    const code = parts.filter(Boolean).join('\n\n');
+
+    // Track the generated code for source map positions
+    if (this.sourceMap) {
+      this._trackCode(code);
+    }
+
+    return code;
+  }
+
+  /**
+   * Transform AST and return result with optional source map
+   * @returns {Object} Result with code and optional sourceMap
+   */
+  transformWithSourceMap() {
+    const code = this.transform();
+
+    if (!this.sourceMap) {
+      return { code, sourceMap: null };
+    }
+
+    return {
+      code,
+      sourceMap: this.sourceMap.toJSON(),
+      sourceMapComment: this.sourceMap.toComment()
+    };
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.4.8",
+  "version": "1.4.9",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -42,6 +42,7 @@
       "default": "./runtime/logger.js"
     },
     "./runtime/hmr": {
+      "types": "./types/hmr.d.ts",
       "default": "./runtime/hmr.js"
     },
     "./compiler": {
@@ -70,8 +71,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze",
+    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze",
     "test:compiler": "node test/compiler.test.js",
+    "test:sourcemap": "node test/sourcemap.test.js",
     "test:pulse": "node test/pulse.test.js",
     "test:dom": "node test/dom.test.js",
     "test:router": "node test/router.test.js",

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
 };