pulse-js-framework 1.7.15 → 1.7.17

package/runtime/ssr-async.js

@@ -0,0 +1,229 @@
+/**
+ * Pulse SSR Async Context - Async operation collection for SSR
+ *
+ * Collects and manages async operations during server-side rendering.
+ * Enables data prefetching before HTML generation.
+ */
+
+// ============================================================================
+// SSR Async Context
+// ============================================================================
+
+/**
+ * Context for collecting async operations during SSR.
+ * Tracks pending promises and caches resolved data for re-renders.
+ */
+export class SSRAsyncContext {
+  constructor() {
+    /** @type {Array<{key: any, promise: Promise}>} */
+    this.pending = [];
+
+    /** @type {Map<any, any>} */
+    this.resolved = new Map();
+
+    /** @type {Map<any, Error>} */
+    this.errors = new Map();
+
+    /** @type {boolean} */
+    this.collecting = true;
+  }
+
+  /**
+   * Register an async operation for collection.
+   * @param {any} key - Unique key for this operation (usually the async function)
+   * @param {Promise} promise - The promise to track
+   */
+  register(key, promise) {
+    if (!this.collecting) return;
+
+    // Wrap promise to capture result
+    const tracked = promise
+      .then(data => {
+        this.resolved.set(key, data);
+        return data;
+      })
+      .catch(error => {
+        this.errors.set(key, error);
+        throw error;
+      });
+
+    this.pending.push({ key, promise: tracked });
+  }
+
+  /**
+   * Check if a result is already cached.
+   * @param {any} key - Operation key
+   * @returns {boolean} True if result is cached
+   */
+  has(key) {
+    return this.resolved.has(key);
+  }
+
+  /**
+   * Get cached result for a key.
+   * @param {any} key - Operation key
+   * @returns {any} Cached result or undefined
+   */
+  get(key) {
+    return this.resolved.get(key);
+  }
+
+  /**
+   * Get error for a key (if the operation failed).
+   * @param {any} key - Operation key
+   * @returns {Error|undefined} Error or undefined
+   */
+  getError(key) {
+    return this.errors.get(key);
+  }
+
+  /**
+   * Wait for all pending async operations to complete.
+   * @param {number} [timeout=5000] - Maximum wait time in ms
+   * @returns {Promise<void>}
+   * @throws {Error} If timeout is exceeded
+   */
+  async waitAll(timeout = 5000) {
+    if (this.pending.length === 0) return;
+
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`[Pulse SSR] Async operations timed out after ${timeout}ms`));
+      }, timeout);
+    });
+
+    // Wait for all promises, catching individual errors
+    const allSettled = Promise.all(
+      this.pending.map(p => p.promise.catch(() => null))
+    );
+
+    await Promise.race([allSettled, timeoutPromise]);
+
+    // Stop collecting after wait
+    this.collecting = false;
+  }
+
+  /**
+   * Get the number of pending operations.
+   * @returns {number}
+   */
+  get pendingCount() {
+    return this.pending.length;
+  }
+
+  /**
+   * Get the number of resolved operations.
+   * @returns {number}
+   */
+  get resolvedCount() {
+    return this.resolved.size;
+  }
+
+  /**
+   * Get the number of failed operations.
+   * @returns {number}
+   */
+  get errorCount() {
+    return this.errors.size;
+  }
+
+  /**
+   * Get all resolved data as a plain object.
+   * @returns {Object} Map of key → value
+   */
+  getAllResolved() {
+    const result = {};
+    for (const [key, value] of this.resolved) {
+      // Use string key if function, otherwise try to serialize
+      const keyStr = typeof key === 'function' ? key.name || 'anonymous' : String(key);
+      result[keyStr] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Reset the context for a new render pass.
+   */
+  reset() {
+    this.pending = [];
+    this.resolved.clear();
+    this.errors.clear();
+    this.collecting = true;
+  }
+}
+
+// ============================================================================
+// Global SSR Async Context
+// ============================================================================
+
+/** @type {SSRAsyncContext|null} */
+let ssrAsyncContext = null;
+
+/**
+ * Get the current SSR async context.
+ * Returns null if not in SSR mode.
+ * @returns {SSRAsyncContext|null}
+ */
+export function getSSRAsyncContext() {
+  return ssrAsyncContext;
+}
+
+/**
+ * Set the SSR async context.
+ * @param {SSRAsyncContext|null} ctx - Context to set, or null to clear
+ */
+export function setSSRAsyncContext(ctx) {
+  ssrAsyncContext = ctx;
+}
+
+/**
+ * Check if currently in SSR async collection mode.
+ * @returns {boolean}
+ */
+export function isCollectingAsync() {
+  return ssrAsyncContext !== null && ssrAsyncContext.collecting;
+}
+
+/**
+ * Register an async operation in the current SSR context.
+ * No-op if not in SSR mode.
+ * @param {any} key - Unique key for this operation
+ * @param {Promise} promise - The promise to track
+ */
+export function registerAsync(key, promise) {
+  if (ssrAsyncContext) {
+    ssrAsyncContext.register(key, promise);
+  }
+}
+
+/**
+ * Get cached async result from current SSR context.
+ * @param {any} key - Operation key
+ * @returns {any} Cached result or undefined
+ */
+export function getCachedAsync(key) {
+  return ssrAsyncContext?.get(key);
+}
+
+/**
+ * Check if an async result is cached in current SSR context.
+ * @param {any} key - Operation key
+ * @returns {boolean}
+ */
+export function hasCachedAsync(key) {
+  return ssrAsyncContext?.has(key) ?? false;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  SSRAsyncContext,
+  getSSRAsyncContext,
+  setSSRAsyncContext,
+  isCollectingAsync,
+  registerAsync,
+  getCachedAsync,
+  hasCachedAsync
+};

package/runtime/ssr-hydrator.js

@@ -0,0 +1,310 @@
+/**
+ * Pulse SSR Hydrator - Client-side hydration utilities
+ *
+ * Provides utilities for hydrating server-rendered HTML by attaching
+ * event listeners and reactive bindings to existing DOM elements.
+ */
+
+// ============================================================================
+// Hydration State
+// ============================================================================
+
+/** @type {boolean} */
+let isHydrating = false;
+
+/** @type {HydrationContext|null} */
+let hydrationCtx = null;
+
+// ============================================================================
+// Hydration Context
+// ============================================================================
+
+/**
+ * @typedef {Object} HydrationContext
+ * @property {Element} root - Root container element
+ * @property {Node|null} cursor - Current position in DOM tree
+ * @property {Array<Function>} cleanups - Cleanup functions for disposal
+ * @property {Array<{element: Element, event: string, handler: Function}>} listeners - Attached event listeners
+ * @property {number} depth - Current nesting depth
+ * @property {boolean} mismatchWarned - Whether a mismatch warning was shown
+ */
+
+/**
+ * Create a new hydration context for a container element.
+ * @param {Element} root - Root container element
+ * @returns {HydrationContext}
+ */
+export function createHydrationContext(root) {
+  return {
+    root,
+    cursor: root.firstChild,
+    cleanups: [],
+    listeners: [],
+    depth: 0,
+    mismatchWarned: false
+  };
+}
+
+// ============================================================================
+// Hydration Mode Control
+// ============================================================================
+
+/**
+ * Enable or disable hydration mode.
+ * @param {boolean} enabled - Whether to enable hydration mode
+ * @param {HydrationContext|null} ctx - Hydration context (required when enabling)
+ */
+export function setHydrationMode(enabled, ctx = null) {
+  isHydrating = enabled;
+  hydrationCtx = enabled ? ctx : null;
+}
+
+/**
+ * Check if currently in hydration mode.
+ * @returns {boolean}
+ */
+export function isHydratingMode() {
+  return isHydrating;
+}
+
+/**
+ * Get the current hydration context.
+ * @returns {HydrationContext|null}
+ */
+export function getHydrationContext() {
+  return hydrationCtx;
+}
+
+// ============================================================================
+// DOM Cursor Navigation
+// ============================================================================
+
+/**
+ * Get the current node at the cursor position.
+ * @param {HydrationContext} ctx - Hydration context
+ * @returns {Node|null}
+ */
+export function getCurrentNode(ctx) {
+  return ctx.cursor;
+}
+
+/**
+ * Advance the cursor to the next sibling.
+ * @param {HydrationContext} ctx - Hydration context
+ */
+export function advanceCursor(ctx) {
+  if (ctx.cursor) {
+    ctx.cursor = ctx.cursor.nextSibling;
+  }
+}
+
+/**
+ * Enter a child scope (for nested elements).
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Element} element - Parent element to enter
+ */
+export function enterChild(ctx, element) {
+  ctx.cursor = element.firstChild;
+  ctx.depth++;
+}
+
+/**
+ * Exit a child scope and restore cursor to parent level.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Element} element - Element we're exiting
+ */
+export function exitChild(ctx, element) {
+  ctx.cursor = element.nextSibling;
+  ctx.depth--;
+}
+
+/**
+ * Skip comment nodes (used as markers).
+ * @param {HydrationContext} ctx - Hydration context
+ */
+export function skipComments(ctx) {
+  while (ctx.cursor && ctx.cursor.nodeType === 8) {
+    ctx.cursor = ctx.cursor.nextSibling;
+  }
+}
+
+// ============================================================================
+// DOM Matching
+// ============================================================================
+
+/**
+ * Check if an element matches expected tag and basic attributes.
+ * @param {Node} node - Node to check
+ * @param {string} expectedTag - Expected tag name (lowercase)
+ * @param {string} [expectedId] - Expected ID (optional)
+ * @param {string} [expectedClass] - Expected class (optional)
+ * @returns {boolean}
+ */
+export function matchesElement(node, expectedTag, expectedId, expectedClass) {
+  if (!node || node.nodeType !== 1) return false;
+
+  const tag = node.tagName?.toLowerCase();
+  if (tag !== expectedTag) return false;
+
+  if (expectedId && node.id !== expectedId) return false;
+  if (expectedClass && !node.classList?.contains(expectedClass)) return false;
+
+  return true;
+}
+
+/**
+ * Log a hydration mismatch warning.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {string} expected - What was expected
+ * @param {Node|null} actual - What was found
+ */
+export function warnMismatch(ctx, expected, actual) {
+  if (ctx.mismatchWarned) return;
+
+  const actualDesc = actual
+    ? `<${actual.tagName?.toLowerCase() || actual.nodeName}>`
+    : 'null';
+
+  console.warn(
+    `[Pulse Hydration] Mismatch at depth ${ctx.depth}: ` +
+    `expected ${expected}, found ${actualDesc}. ` +
+    `This may cause hydration errors.`
+  );
+
+  ctx.mismatchWarned = true;
+}
+
+// ============================================================================
+// Event Listener Management
+// ============================================================================
+
+/**
+ * Register an event listener during hydration.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Element} element - Target element
+ * @param {string} event - Event name
+ * @param {Function} handler - Event handler
+ * @param {Object} [options] - Event listener options
+ */
+export function registerListener(ctx, element, event, handler, options) {
+  element.addEventListener(event, handler, options);
+  ctx.listeners.push({ element, event, handler, options });
+}
+
+/**
+ * Register a cleanup function.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Function} cleanup - Cleanup function
+ */
+export function registerCleanup(ctx, cleanup) {
+  ctx.cleanups.push(cleanup);
+}
+
+// ============================================================================
+// Hydration Disposal
+// ============================================================================
+
+/**
+ * Dispose of all hydration resources.
+ * Removes event listeners and runs cleanup functions.
+ * @param {HydrationContext} ctx - Hydration context
+ */
+export function disposeHydration(ctx) {
+  // Remove all event listeners
+  for (const { element, event, handler, options } of ctx.listeners) {
+    element.removeEventListener(event, handler, options);
+  }
+  ctx.listeners = [];
+
+  // Run cleanup functions
+  for (const cleanup of ctx.cleanups) {
+    try {
+      cleanup();
+    } catch (e) {
+      console.error('[Pulse Hydration] Cleanup error:', e);
+    }
+  }
+  ctx.cleanups = [];
+}
+
+// ============================================================================
+// Hydration Helpers
+// ============================================================================
+
+/**
+ * Find the next element matching a tag within the current scope.
+ * Useful for recovering from mismatches.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {string} tag - Tag name to find
+ * @returns {Element|null}
+ */
+export function findNextElement(ctx, tag) {
+  let node = ctx.cursor;
+  while (node) {
+    if (node.nodeType === 1 && node.tagName?.toLowerCase() === tag) {
+      return node;
+    }
+    node = node.nextSibling;
+  }
+  return null;
+}
+
+/**
+ * Count remaining elements in the current scope.
+ * Useful for debugging hydration issues.
+ * @param {HydrationContext} ctx - Hydration context
+ * @returns {number}
+ */
+export function countRemaining(ctx) {
+  let count = 0;
+  let node = ctx.cursor;
+  while (node) {
+    if (node.nodeType === 1) count++;
+    node = node.nextSibling;
+  }
+  return count;
+}
+
+/**
+ * Check if hydration is complete (no more nodes to process).
+ * @param {HydrationContext} ctx - Hydration context
+ * @returns {boolean}
+ */
+export function isHydrationComplete(ctx) {
+  return ctx.cursor === null && ctx.depth === 0;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  // Mode control
+  setHydrationMode,
+  isHydratingMode,
+  getHydrationContext,
+
+  // Context
+  createHydrationContext,
+
+  // Navigation
+  getCurrentNode,
+  advanceCursor,
+  enterChild,
+  exitChild,
+  skipComments,
+
+  // Matching
+  matchesElement,
+  warnMismatch,
+  findNextElement,
+
+  // Resources
+  registerListener,
+  registerCleanup,
+  disposeHydration,
+
+  // Helpers
+  countRemaining,
+  isHydrationComplete
+};