pulse-js-framework 1.4.9 → 1.5.0

package/core/errors.js

@@ -0,0 +1,300 @@
+/**
+ * Pulse Error Classes - Structured error handling for the framework
+ * @module pulse-js-framework/core/errors
+ */
+
+/**
+ * Base error class for all Pulse framework errors.
+ * Provides source location tracking and code snippet formatting.
+ */
+export class PulseError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} [options={}] - Error options
+   * @param {number} [options.line] - Line number where error occurred
+   * @param {number} [options.column] - Column number where error occurred
+   * @param {string} [options.file] - Source file path
+   * @param {string} [options.code] - Error code for documentation lookup
+   * @param {string} [options.source] - Original source code
+   * @param {string} [options.suggestion] - Helpful suggestion to fix the error
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'PulseError';
+    this.line = options.line ?? null;
+    this.column = options.column ?? null;
+    this.file = options.file ?? null;
+    this.code = options.code ?? 'PULSE_ERROR';
+    this.source = options.source ?? null;
+    this.suggestion = options.suggestion ?? null;
+  }
+
+  /**
+   * Format the error with a code snippet showing context
+   * @param {string} [source] - Source code to use (overrides this.source)
+   * @param {number} [contextLines=2] - Number of lines to show before/after error
+   * @returns {string} Formatted error with code snippet
+   */
+  formatWithSnippet(source = this.source, contextLines = 2) {
+    if (!this.line || !source) {
+      return this.toString();
+    }
+
+    const lines = source.split('\n');
+    const start = Math.max(0, this.line - 1 - contextLines);
+    const end = Math.min(lines.length, this.line + contextLines);
+    const gutterWidth = String(end).length;
+
+    let output = `\n${this.name}: ${this.message}\n`;
+    output += `  at ${this.file || '<anonymous>'}:${this.line}:${this.column || 1}\n\n`;
+
+    for (let i = start; i < end; i++) {
+      const lineNum = i + 1;
+      const isErrorLine = lineNum === this.line;
+      const prefix = isErrorLine ? '>' : ' ';
+      const gutter = String(lineNum).padStart(gutterWidth);
+      output += `${prefix} ${gutter} | ${lines[i]}\n`;
+
+      if (isErrorLine && this.column) {
+        const padding = ' '.repeat(gutterWidth + 3 + Math.max(0, this.column - 1));
+        output += `  ${padding}^\n`;
+      }
+    }
+
+    if (this.suggestion) {
+      output += `\n  Suggestion: ${this.suggestion}\n`;
+    }
+
+    if (this.code && this.code !== 'PULSE_ERROR') {
+      output += `\n  Error code: ${this.code}\n`;
+    }
+
+    return output;
+  }
+
+  /**
+   * Convert to plain object for JSON serialization
+   * @returns {Object} Plain object representation
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      line: this.line,
+      column: this.column,
+      file: this.file,
+      code: this.code,
+      suggestion: this.suggestion
+    };
+  }
+}
+
+// ============================================================================
+// Compiler Errors
+// ============================================================================
+
+/**
+ * Base class for all compilation errors
+ */
+export class CompileError extends PulseError {
+  constructor(message, options = {}) {
+    super(message, { code: 'COMPILE_ERROR', ...options });
+    this.name = 'CompileError';
+  }
+}
+
+/**
+ * Error during lexical analysis (tokenization)
+ */
+export class LexerError extends CompileError {
+  constructor(message, options = {}) {
+    super(message, { code: 'LEXER_ERROR', ...options });
+    this.name = 'LexerError';
+  }
+}
+
+/**
+ * Error during parsing (AST construction)
+ */
+export class ParserError extends CompileError {
+  /**
+   * @param {string} message - Error message
+   * @param {Object} [options={}] - Error options
+   * @param {Object} [options.token] - The problematic token
+   */
+  constructor(message, options = {}) {
+    super(message, { code: 'PARSER_ERROR', ...options });
+    this.name = 'ParserError';
+    this.token = options.token ?? null;
+  }
+}
+
+/**
+ * Error during code transformation/generation
+ */
+export class TransformError extends CompileError {
+  constructor(message, options = {}) {
+    super(message, { code: 'TRANSFORM_ERROR', ...options });
+    this.name = 'TransformError';
+  }
+}
+
+// ============================================================================
+// Runtime Errors
+// ============================================================================
+
+/**
+ * Base class for all runtime errors
+ */
+export class RuntimeError extends PulseError {
+  constructor(message, options = {}) {
+    super(message, { code: 'RUNTIME_ERROR', ...options });
+    this.name = 'RuntimeError';
+  }
+}
+
+/**
+ * Error in the reactivity system (effects, computed values)
+ */
+export class ReactivityError extends RuntimeError {
+  constructor(message, options = {}) {
+    super(message, { code: 'REACTIVITY_ERROR', ...options });
+    this.name = 'ReactivityError';
+  }
+}
+
+/**
+ * Error in DOM operations
+ */
+export class DOMError extends RuntimeError {
+  constructor(message, options = {}) {
+    super(message, { code: 'DOM_ERROR', ...options });
+    this.name = 'DOMError';
+  }
+}
+
+/**
+ * Error in store operations
+ */
+export class StoreError extends RuntimeError {
+  constructor(message, options = {}) {
+    super(message, { code: 'STORE_ERROR', ...options });
+    this.name = 'StoreError';
+  }
+}
+
+/**
+ * Error in router operations
+ */
+export class RouterError extends RuntimeError {
+  constructor(message, options = {}) {
+    super(message, { code: 'ROUTER_ERROR', ...options });
+    this.name = 'RouterError';
+  }
+}
+
+// ============================================================================
+// CLI Errors
+// ============================================================================
+
+/**
+ * Base class for CLI errors
+ */
+export class CLIError extends PulseError {
+  constructor(message, options = {}) {
+    super(message, { code: 'CLI_ERROR', ...options });
+    this.name = 'CLIError';
+  }
+}
+
+/**
+ * Configuration file error
+ */
+export class ConfigError extends CLIError {
+  constructor(message, options = {}) {
+    super(message, { code: 'CONFIG_ERROR', ...options });
+    this.name = 'ConfigError';
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Common error suggestions based on error patterns
+ */
+export const SUGGESTIONS = {
+  'undefined-variable': (name) =>
+    `Did you forget to declare '${name}' in the state block or import it?`,
+  'duplicate-declaration': (name) =>
+    `Remove the duplicate declaration of '${name}'`,
+  'unexpected-token': (expected, got) =>
+    `Expected ${expected} but got '${got}'. Check for missing braces, quotes, or semicolons.`,
+  'missing-closing-brace': () =>
+    `Add the missing closing brace '}'`,
+  'missing-closing-paren': () =>
+    `Add the missing closing parenthesis ')'`,
+  'invalid-directive': (name) =>
+    `'${name}' is not a valid directive. Valid directives: @if, @each, @click, @link, @outlet`,
+  'empty-block': (blockName) =>
+    `The ${blockName} block is empty. Add content or remove the block.`
+};
+
+/**
+ * Format an error with source code context
+ * @param {Error} error - The error to format
+ * @param {string} [source] - Source code for context
+ * @returns {string} Formatted error string
+ */
+export function formatError(error, source) {
+  if (error instanceof PulseError) {
+    return error.formatWithSnippet(source);
+  }
+
+  // Handle plain Error objects with line/column properties
+  if (error.line && source) {
+    const pulseError = new PulseError(error.message, {
+      line: error.line,
+      column: error.column,
+      file: error.file
+    });
+    return pulseError.formatWithSnippet(source);
+  }
+
+  return error.stack || error.message;
+}
+
+/**
+ * Create a parser error from a token
+ * @param {string} message - Error message
+ * @param {Object} token - Token object with line/column info
+ * @param {Object} [options={}] - Additional options
+ * @returns {ParserError} The created error
+ */
+export function createParserError(message, token, options = {}) {
+  return new ParserError(message, {
+    line: token?.line || 1,
+    column: token?.column || 1,
+    token,
+    ...options
+  });
+}
+
+export default {
+  PulseError,
+  CompileError,
+  LexerError,
+  ParserError,
+  TransformError,
+  RuntimeError,
+  ReactivityError,
+  DOMError,
+  StoreError,
+  RouterError,
+  CLIError,
+  ConfigError,
+  SUGGESTIONS,
+  formatError,
+  createParserError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.4.9",
+  "version": "1.5.0",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -45,6 +45,8 @@
       "types": "./types/hmr.d.ts",
       "default": "./runtime/hmr.js"
     },
+    "./runtime/lru-cache": "./runtime/lru-cache.js",
+    "./runtime/utils": "./runtime/utils.js",
     "./compiler": {
       "types": "./types/index.d.ts",
       "default": "./compiler/index.js"
@@ -52,6 +54,7 @@
     "./compiler/lexer": "./compiler/lexer.js",
     "./compiler/parser": "./compiler/parser.js",
     "./compiler/transformer": "./compiler/transformer.js",
+    "./core/errors": "./core/errors.js",
     "./vite": {
       "types": "./types/index.d.ts",
       "default": "./loader/vite-plugin.js"
@@ -62,6 +65,7 @@
   "files": [
     "index.js",
     "cli/",
+    "core/",
     "runtime/",
     "compiler/",
     "loader/",
@@ -83,7 +87,8 @@
     "test:format": "node test/format.test.js",
     "test:analyze": "node test/analyze.test.js",
     "build:netlify": "node scripts/build-netlify.js",
-    "version": "node scripts/sync-version.js"
+    "version": "node scripts/sync-version.js",
+    "docs": "node cli/index.js dev docs"
   },
   "keywords": [
     "framework",
@@ -113,7 +118,5 @@
     "node": ">=18.0.0"
   },
   "dependencies": {},
-  "devDependencies": {
-    "linkedom": "^0.16.8"
-  }
+  "devDependencies": {}
 }

package/runtime/dom.js

@@ -7,12 +7,26 @@
 
 import { effect, pulse, batch, onCleanup } from './pulse.js';
 import { loggers } from './logger.js';
+import { LRUCache } from './lru-cache.js';
 
 const log = loggers.dom;
 
-// Selector cache for parseSelector
-const selectorCache = new Map();
-const SELECTOR_CACHE_MAX = 500;
+// =============================================================================
+// SELECTOR CACHE
+// =============================================================================
+// LRU (Least Recently Used) cache for parseSelector results.
+//
+// Why LRU instead of Map?
+// - Apps typically reuse the same selectors (e.g., 'div.container', 'button.primary')
+// - Without eviction, memory grows unbounded in long-running apps
+// - LRU keeps frequently-used selectors hot while evicting rare ones
+//
+// Capacity: 500 selectors (chosen based on typical SPA component count)
+// - Most apps use 50-200 unique selectors
+// - 500 provides headroom for dynamic selectors without excessive memory
+//
+// Cache hit returns a shallow copy to prevent mutation of cached config
+const selectorCache = new LRUCache(500);
 
 // Lifecycle tracking
 let mountCallbacks = [];
@@ -113,12 +127,7 @@ export function parseSelector(selector) {
     config.attrs[key] = value;
   }
 
-  // Cache the result (with size limit to prevent memory leaks)
-  if (selectorCache.size >= SELECTOR_CACHE_MAX) {
-    // Remove oldest entry (first key)
-    const firstKey = selectorCache.keys().next().value;
-    selectorCache.delete(firstKey);
-  }
+  // Cache the result (LRU cache handles eviction automatically)
   selectorCache.set(selector, config);
 
   // Return a copy
@@ -311,6 +320,37 @@ export function on(element, event, handler, options) {
 
 /**
  * Create a reactive list with efficient keyed diffing
+ *
+ * LIST DIFFING ALGORITHM:
+ * -----------------------
+ * This uses a keyed reconciliation strategy to minimize DOM operations:
+ *
+ * 1. KEY EXTRACTION: Each item gets a unique key via keyFn (defaults to index)
+ *    Good keys: item.id, item.uuid (stable across re-renders)
+ *    Bad keys: array index (causes unnecessary re-renders on reorder)
+ *
+ * 2. RECONCILIATION PHASES:
+ *    a) Build a map of new items by key
+ *    b) For existing keys: reuse the DOM nodes (no re-creation)
+ *    c) For removed keys: remove DOM nodes and run cleanup
+ *    d) For new keys: create DOM nodes via template function
+ *
+ * 3. REORDERING: Uses a single forward pass:
+ *    - Tracks previous node position with prevNode cursor
+ *    - Only moves nodes that are out of position
+ *    - Nodes already in correct position are skipped (no DOM operation)
+ *
+ * 4. BOUNDARY MARKERS: Uses comment nodes to track list boundaries:
+ *    - startMarker: Insertion point for first item
+ *    - endMarker: End boundary (not currently used but reserved)
+ *
+ * COMPLEXITY: O(n) for reconciliation + O(m) DOM moves where m <= n
+ * Best case (no changes): O(n) comparisons, 0 DOM operations
+ *
+ * @param {Function|Pulse} getItems - Items source (reactive)
+ * @param {Function} template - (item, index) => Node | Node[]
+ * @param {Function} keyFn - (item, index) => key (default: index)
+ * @returns {DocumentFragment} Container fragment with reactive list
  */
 export function list(getItems, template, keyFn = (item, i) => i) {
   const container = document.createDocumentFragment();
@@ -506,13 +546,24 @@ export function model(element, pulseValue) {
 
 /**
  * Mount an element to a target
+ * @param {string|HTMLElement} target - CSS selector or DOM element
+ * @param {Node} element - Element to mount
+ * @returns {Function} Unmount function
+ * @throws {Error} If target element is not found
  */
 export function mount(target, element) {
+  const originalTarget = target;
   if (typeof target === 'string') {
     target = document.querySelector(target);
   }
   if (!target) {
-    throw new Error('Mount target not found');
+    const selector = typeof originalTarget === 'string' ? originalTarget : '(element)';
+    throw new Error(
+      `[Pulse] Mount target not found: "${selector}". ` +
+      `Ensure the element exists in the DOM before mounting. ` +
+      `Tip: Use document.addEventListener('DOMContentLoaded', () => mount(...)) ` +
+      `or place your script at the end of <body>.`
+    );
   }
   target.appendChild(element);
   return () => {

package/runtime/lru-cache.js

@@ -0,0 +1,145 @@
+/**
+ * LRU (Least Recently Used) Cache
+ * @module pulse-js-framework/runtime/lru-cache
+ *
+ * A simple LRU cache implementation using Map's insertion order.
+ * When capacity is reached, the least recently used item is evicted.
+ */
+
+/**
+ * LRU Cache implementation
+ * @template K, V
+ */
+export class LRUCache {
+  /** @type {number} */
+  #capacity;
+
+  /** @type {Map<K, V>} */
+  #cache = new Map();
+
+  /**
+   * Create an LRU cache
+   * @param {number} capacity - Maximum number of items to store
+   */
+  constructor(capacity) {
+    if (capacity <= 0) {
+      throw new Error('LRU cache capacity must be greater than 0');
+    }
+    this.#capacity = capacity;
+  }
+
+  /**
+   * Get an item from the cache
+   * Accessing an item moves it to the "most recently used" position
+   * @param {K} key - Cache key
+   * @returns {V|undefined} The cached value or undefined if not found
+   */
+  get(key) {
+    if (!this.#cache.has(key)) {
+      return undefined;
+    }
+
+    // Move to end (most recently used) by re-inserting
+    const value = this.#cache.get(key);
+    this.#cache.delete(key);
+    this.#cache.set(key, value);
+    return value;
+  }
+
+  /**
+   * Set an item in the cache
+   * If the cache is at capacity, evicts the least recently used item
+   * @param {K} key - Cache key
+   * @param {V} value - Value to store
+   * @returns {LRUCache} this (for chaining)
+   */
+  set(key, value) {
+    // If key exists, delete first to update position
+    if (this.#cache.has(key)) {
+      this.#cache.delete(key);
+    } else if (this.#cache.size >= this.#capacity) {
+      // Remove oldest (first item in Map)
+      const oldest = this.#cache.keys().next().value;
+      this.#cache.delete(oldest);
+    }
+
+    this.#cache.set(key, value);
+    return this;
+  }
+
+  /**
+   * Check if a key exists in the cache
+   * Note: This does NOT update the item's position
+   * @param {K} key - Cache key
+   * @returns {boolean} True if key exists
+   */
+  has(key) {
+    return this.#cache.has(key);
+  }
+
+  /**
+   * Delete an item from the cache
+   * @param {K} key - Cache key
+   * @returns {boolean} True if item was deleted
+   */
+  delete(key) {
+    return this.#cache.delete(key);
+  }
+
+  /**
+   * Clear all items from the cache
+   */
+  clear() {
+    this.#cache.clear();
+  }
+
+  /**
+   * Get the current number of items in the cache
+   * @returns {number} Current size
+   */
+  get size() {
+    return this.#cache.size;
+  }
+
+  /**
+   * Get the maximum capacity of the cache
+   * @returns {number} Maximum capacity
+   */
+  get capacity() {
+    return this.#capacity;
+  }
+
+  /**
+   * Get all keys in the cache (oldest to newest)
+   * @returns {IterableIterator<K>} Iterator of keys
+   */
+  keys() {
+    return this.#cache.keys();
+  }
+
+  /**
+   * Get all values in the cache (oldest to newest)
+   * @returns {IterableIterator<V>} Iterator of values
+   */
+  values() {
+    return this.#cache.values();
+  }
+
+  /**
+   * Get all entries in the cache (oldest to newest)
+   * @returns {IterableIterator<[K, V]>} Iterator of [key, value] pairs
+   */
+  entries() {
+    return this.#cache.entries();
+  }
+
+  /**
+   * Iterate over all entries
+   * @param {function(V, K, LRUCache): void} callback - Called for each entry
+   */
+  forEach(callback) {
+    this.#cache.forEach((value, key) => callback(value, key, this));
+  }
+}
+
+export default LRUCache;

package/runtime/native.js

@@ -21,7 +21,12 @@ export function isNativeAvailable() {
  */
 export function getNative() {
   if (!isNativeAvailable()) {
-    throw new Error('PulseMobile is not available. Include pulse-native.js in your app.');
+    throw new Error(
+      '[Pulse Native] PulseMobile bridge is not available. ' +
+      'This API only works in a Pulse native mobile app. ' +
+      'For web, use isNativeAvailable() to check before calling native APIs, ' +
+      'or use getPlatform() to detect the current environment.'
+    );
   }
   return window.PulseMobile;
 }

package/runtime/pulse.js

@@ -22,6 +22,43 @@ import { loggers } from './logger.js';
 
 const log = loggers.pulse;
 
+// =============================================================================
+// REACTIVE DEPENDENCY TRACKING ALGORITHM
+// =============================================================================
+//
+// This module implements a push-based reactive system using automatic dependency
+// tracking. Here's how it works:
+//
+// 1. READING (Dependency Collection)
+//    - When an effect runs, `context.currentEffect` points to it
+//    - When a pulse's get() is called, it checks if there's a currentEffect
+//    - If so, it adds the effect to its subscribers and vice versa
+//    - This creates a bidirectional link: pulse knows who depends on it,
+//      effect knows what it depends on
+//
+// 2. WRITING (Change Notification)
+//    - When a pulse's set() is called with a new value, it notifies subscribers
+//    - Each subscriber (effect) is either run immediately or queued for batching
+//    - Effects re-run, clearing old dependencies and collecting new ones
+//
+// 3. BATCHING (Performance Optimization)
+//    - batch() increments batchDepth and delays effect execution
+//    - Effects are queued in pendingEffects instead of running immediately
+//    - When batch completes, flushEffects() runs all queued effects
+//    - Nested batches are handled by only flushing at depth 0
+//
+// 4. COMPUTED VALUES (Derived State)
+//    - Computed pulses wrap a function and cache its result
+//    - They use the same dependency tracking to know when to recompute
+//    - Lazy computed values only recompute when read (pull-based optimization)
+//
+// 5. CLEANUP (Memory Management)
+//    - Effects can return a cleanup function called before re-run or disposal
+//    - On re-run, old dependencies are cleared before collecting new ones
+//    - This prevents memory leaks and stale subscriptions
+//
+// =============================================================================
+
 /**
  * @typedef {Object} ReactiveContext
  * @property {EffectFn|null} currentEffect - Currently executing effect for dependency tracking
@@ -509,11 +546,18 @@ export function computed(fn, options = {}) {
 
   // Override set to make it read-only
   p.set = () => {
-    throw new Error('Cannot set a computed pulse directly');
+    throw new Error(
+      '[Pulse] Cannot set a computed value directly. ' +
+      'Computed values are derived from other pulses and update automatically. ' +
+      'Modify the source pulse(s) instead.'
+    );
   };
 
   p.update = () => {
-    throw new Error('Cannot update a computed pulse directly');
+    throw new Error(
+      '[Pulse] Cannot update a computed value directly. ' +
+      'Computed values are read-only. Modify the source pulse(s) instead.'
+    );
   };
 
   // Add dispose method

package/runtime/router.js

@@ -15,6 +15,9 @@
 
 import { pulse, effect, batch } from './pulse.js';
 import { el } from './dom.js';
+import { loggers } from './logger.js';
+
+const log = loggers.router;
 
 /**
  * Lazy load helper for route components
@@ -126,7 +129,7 @@ export function lazy(importFn, options = {}) {
         if (ErrorComponent) {
           container.replaceChildren(ErrorComponent(err));
         } else {
-          console.error('Lazy load error:', err);
+          log.error('Lazy load error:', err);
           container.replaceChildren(
             el('div.lazy-error', `Failed to load component: ${err.message}`)
           );