zero-query 0.5.2 → 0.7.5

package/src/diff.js

@@ -0,0 +1,280 @@
+/**
+ * zQuery Diff — Lightweight DOM morphing engine
+ *
+ * Patches an existing DOM tree to match new HTML without destroying nodes
+ * that haven't changed. Preserves focus, scroll positions, third-party
+ * widget state, video playback, and other live DOM state.
+ *
+ * Approach: walk old and new trees in parallel, reconcile node by node.
+ * Keyed elements (via `z-key`) get matched across position changes.
+ */
+
+// ---------------------------------------------------------------------------
+// morph(existingRoot, newHTML) — patch existing DOM to match newHTML
+// ---------------------------------------------------------------------------
+
+/**
+ * Morph an existing DOM element's children to match new HTML.
+ * Only touches nodes that actually differ.
+ *
+ * @param {Element} rootEl — The live DOM container to patch
+ * @param {string} newHTML — The desired HTML string
+ */
+export function morph(rootEl, newHTML) {
+  const template = document.createElement('template');
+  template.innerHTML = newHTML;
+  const newRoot = template.content;
+
+  // Convert to element for consistent handling — wrap in a div if needed
+  const tempDiv = document.createElement('div');
+  while (newRoot.firstChild) tempDiv.appendChild(newRoot.firstChild);
+
+  _morphChildren(rootEl, tempDiv);
+}
+
+/**
+ * Reconcile children of `oldParent` to match `newParent`.
+ *
+ * @param {Element} oldParent — live DOM parent
+ * @param {Element} newParent — desired state parent
+ */
+function _morphChildren(oldParent, newParent) {
+  const oldChildren = [...oldParent.childNodes];
+  const newChildren = [...newParent.childNodes];
+
+  // Build key maps for keyed element matching
+  const oldKeyMap = new Map();
+  const newKeyMap = new Map();
+
+  for (let i = 0; i < oldChildren.length; i++) {
+    const key = _getKey(oldChildren[i]);
+    if (key != null) oldKeyMap.set(key, i);
+  }
+  for (let i = 0; i < newChildren.length; i++) {
+    const key = _getKey(newChildren[i]);
+    if (key != null) newKeyMap.set(key, i);
+  }
+
+  const hasKeys = oldKeyMap.size > 0 || newKeyMap.size > 0;
+
+  if (hasKeys) {
+    _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, newKeyMap);
+  } else {
+    _morphChildrenUnkeyed(oldParent, oldChildren, newChildren);
+  }
+}
+
+/**
+ * Unkeyed reconciliation — positional matching.
+ */
+function _morphChildrenUnkeyed(oldParent, oldChildren, newChildren) {
+  const maxLen = Math.max(oldChildren.length, newChildren.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const oldNode = oldChildren[i];
+    const newNode = newChildren[i];
+
+    if (!oldNode && newNode) {
+      // New node — append
+      oldParent.appendChild(newNode.cloneNode(true));
+    } else if (oldNode && !newNode) {
+      // Extra old node — remove
+      oldParent.removeChild(oldNode);
+    } else if (oldNode && newNode) {
+      _morphNode(oldParent, oldNode, newNode);
+    }
+  }
+}
+
+/**
+ * Keyed reconciliation — match by z-key, reorder minimal moves.
+ */
+function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, newKeyMap) {
+  // Track which old nodes are consumed
+  const consumed = new Set();
+
+  // Step 1: Build ordered list of matched old nodes for new children
+  const newLen = newChildren.length;
+  const matched = new Array(newLen); // matched[newIdx] = oldNode | null
+
+  for (let i = 0; i < newLen; i++) {
+    const key = _getKey(newChildren[i]);
+    if (key != null && oldKeyMap.has(key)) {
+      const oldIdx = oldKeyMap.get(key);
+      matched[i] = oldChildren[oldIdx];
+      consumed.add(oldIdx);
+    } else {
+      matched[i] = null;
+    }
+  }
+
+  // Step 2: Remove old nodes that are not in the new tree
+  for (let i = oldChildren.length - 1; i >= 0; i--) {
+    if (!consumed.has(i)) {
+      const key = _getKey(oldChildren[i]);
+      if (key != null && !newKeyMap.has(key)) {
+        oldParent.removeChild(oldChildren[i]);
+      } else if (key == null) {
+        // Unkeyed old node — will be handled positionally below
+      }
+    }
+  }
+
+  // Step 3: Insert/reorder/morph
+  let cursor = oldParent.firstChild;
+  const unkeyedOld = oldChildren.filter((n, i) => !consumed.has(i) && _getKey(n) == null);
+  let unkeyedIdx = 0;
+
+  for (let i = 0; i < newLen; i++) {
+    const newNode = newChildren[i];
+    const newKey = _getKey(newNode);
+    let oldNode = matched[i];
+
+    if (!oldNode && newKey == null) {
+      // Try to match an unkeyed old node positionally
+      oldNode = unkeyedOld[unkeyedIdx++] || null;
+    }
+
+    if (oldNode) {
+      // Move into position if needed
+      if (oldNode !== cursor) {
+        oldParent.insertBefore(oldNode, cursor);
+      }
+      // Morph in place
+      _morphNode(oldParent, oldNode, newNode);
+      cursor = oldNode.nextSibling;
+    } else {
+      // Insert new node
+      const clone = newNode.cloneNode(true);
+      if (cursor) {
+        oldParent.insertBefore(clone, cursor);
+      } else {
+        oldParent.appendChild(clone);
+      }
+      // cursor stays the same — new node is before it
+    }
+  }
+
+  // Remove any remaining unkeyed old nodes at the end
+  while (unkeyedIdx < unkeyedOld.length) {
+    const leftover = unkeyedOld[unkeyedIdx++];
+    if (leftover.parentNode === oldParent) {
+      oldParent.removeChild(leftover);
+    }
+  }
+
+  // Remove any remaining keyed old nodes that weren't consumed
+  for (let i = 0; i < oldChildren.length; i++) {
+    if (!consumed.has(i)) {
+      const node = oldChildren[i];
+      if (node.parentNode === oldParent && _getKey(node) != null && !newKeyMap.has(_getKey(node))) {
+        oldParent.removeChild(node);
+      }
+    }
+  }
+}
+
+/**
+ * Morph a single node in place.
+ */
+function _morphNode(parent, oldNode, newNode) {
+  // Text / comment nodes — just update content
+  if (oldNode.nodeType === 3 || oldNode.nodeType === 8) {
+    if (newNode.nodeType === oldNode.nodeType) {
+      if (oldNode.nodeValue !== newNode.nodeValue) {
+        oldNode.nodeValue = newNode.nodeValue;
+      }
+      return;
+    }
+    // Different node types — replace
+    parent.replaceChild(newNode.cloneNode(true), oldNode);
+    return;
+  }
+
+  // Different node types or tag names — replace entirely
+  if (oldNode.nodeType !== newNode.nodeType ||
+      oldNode.nodeName !== newNode.nodeName) {
+    parent.replaceChild(newNode.cloneNode(true), oldNode);
+    return;
+  }
+
+  // Both are elements — diff attributes then recurse children
+  if (oldNode.nodeType === 1) {
+    _morphAttributes(oldNode, newNode);
+
+    // Special elements: don't recurse into their children
+    // (textarea value, input value, select, etc.)
+    const tag = oldNode.nodeName;
+    if (tag === 'INPUT') {
+      _syncInputValue(oldNode, newNode);
+      return;
+    }
+    if (tag === 'TEXTAREA') {
+      if (oldNode.value !== newNode.textContent) {
+        oldNode.value = newNode.textContent || '';
+      }
+      return;
+    }
+    if (tag === 'SELECT') {
+      // Recurse children (options) then sync value
+      _morphChildren(oldNode, newNode);
+      if (oldNode.value !== newNode.value) {
+        oldNode.value = newNode.value;
+      }
+      return;
+    }
+
+    // Generic element — recurse children
+    _morphChildren(oldNode, newNode);
+  }
+}
+
+/**
+ * Sync attributes from newEl onto oldEl.
+ */
+function _morphAttributes(oldEl, newEl) {
+  // Add/update attributes
+  const newAttrs = newEl.attributes;
+  for (let i = 0; i < newAttrs.length; i++) {
+    const attr = newAttrs[i];
+    if (oldEl.getAttribute(attr.name) !== attr.value) {
+      oldEl.setAttribute(attr.name, attr.value);
+    }
+  }
+
+  // Remove stale attributes
+  const oldAttrs = oldEl.attributes;
+  for (let i = oldAttrs.length - 1; i >= 0; i--) {
+    const attr = oldAttrs[i];
+    if (!newEl.hasAttribute(attr.name)) {
+      oldEl.removeAttribute(attr.name);
+    }
+  }
+}
+
+/**
+ * Sync input element value, checked, disabled states.
+ */
+function _syncInputValue(oldEl, newEl) {
+  const type = (oldEl.type || '').toLowerCase();
+
+  if (type === 'checkbox' || type === 'radio') {
+    if (oldEl.checked !== newEl.checked) oldEl.checked = newEl.checked;
+  } else {
+    if (oldEl.value !== (newEl.getAttribute('value') || '')) {
+      oldEl.value = newEl.getAttribute('value') || '';
+    }
+  }
+
+  // Sync disabled
+  if (oldEl.disabled !== newEl.disabled) oldEl.disabled = newEl.disabled;
+}
+
+/**
+ * Get the reconciliation key from a node (z-key attribute).
+ * @returns {string|null}
+ */
+function _getKey(node) {
+  if (node.nodeType !== 1) return null;
+  return node.getAttribute('z-key') || null;
+}

package/src/errors.js

@@ -0,0 +1,155 @@
+/**
+ * zQuery Errors — Structured error handling system
+ *
+ * Provides typed error classes and a configurable error handler so that
+ * errors surface consistently across all modules (reactive, component,
+ * router, store, expression parser, HTTP, etc.).
+ *
+ * Default behaviour: errors are logged via console.warn/error.
+ * Users can override with $.onError(handler) to integrate with their
+ * own logging, crash-reporting, or UI notification system.
+ */
+
+// ---------------------------------------------------------------------------
+// Error codes — every zQuery error has a unique code for programmatic use
+// ---------------------------------------------------------------------------
+export const ErrorCode = Object.freeze({
+  // Reactive
+  REACTIVE_CALLBACK:   'ZQ_REACTIVE_CALLBACK',
+  SIGNAL_CALLBACK:     'ZQ_SIGNAL_CALLBACK',
+  EFFECT_EXEC:         'ZQ_EFFECT_EXEC',
+
+  // Expression parser
+  EXPR_PARSE:          'ZQ_EXPR_PARSE',
+  EXPR_EVAL:           'ZQ_EXPR_EVAL',
+  EXPR_UNSAFE_ACCESS:  'ZQ_EXPR_UNSAFE_ACCESS',
+
+  // Component
+  COMP_INVALID_NAME:   'ZQ_COMP_INVALID_NAME',
+  COMP_NOT_FOUND:      'ZQ_COMP_NOT_FOUND',
+  COMP_MOUNT_TARGET:   'ZQ_COMP_MOUNT_TARGET',
+  COMP_RENDER:         'ZQ_COMP_RENDER',
+  COMP_LIFECYCLE:      'ZQ_COMP_LIFECYCLE',
+  COMP_RESOURCE:       'ZQ_COMP_RESOURCE',
+  COMP_DIRECTIVE:      'ZQ_COMP_DIRECTIVE',
+
+  // Router
+  ROUTER_LOAD:         'ZQ_ROUTER_LOAD',
+  ROUTER_GUARD:        'ZQ_ROUTER_GUARD',
+  ROUTER_RESOLVE:      'ZQ_ROUTER_RESOLVE',
+
+  // Store
+  STORE_ACTION:        'ZQ_STORE_ACTION',
+  STORE_MIDDLEWARE:     'ZQ_STORE_MIDDLEWARE',
+  STORE_SUBSCRIBE:     'ZQ_STORE_SUBSCRIBE',
+
+  // HTTP
+  HTTP_REQUEST:        'ZQ_HTTP_REQUEST',
+  HTTP_TIMEOUT:        'ZQ_HTTP_TIMEOUT',
+  HTTP_INTERCEPTOR:    'ZQ_HTTP_INTERCEPTOR',
+  HTTP_PARSE:          'ZQ_HTTP_PARSE',
+
+  // General
+  INVALID_ARGUMENT:    'ZQ_INVALID_ARGUMENT',
+});
+
+
+// ---------------------------------------------------------------------------
+// ZQueryError — custom error class
+// ---------------------------------------------------------------------------
+export class ZQueryError extends Error {
+  /**
+   * @param {string} code    — one of ErrorCode values
+   * @param {string} message — human-readable description
+   * @param {object} [context] — extra data (component name, expression, etc.)
+   * @param {Error}  [cause]   — original error
+   */
+  constructor(code, message, context = {}, cause) {
+    super(message);
+    this.name = 'ZQueryError';
+    this.code = code;
+    this.context = context;
+    if (cause) this.cause = cause;
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+let _errorHandler = null;
+
+/**
+ * Register a global error handler.
+ * Called whenever zQuery catches an error internally.
+ *
+ * @param {Function|null} handler — (error: ZQueryError) => void
+ */
+export function onError(handler) {
+  _errorHandler = typeof handler === 'function' ? handler : null;
+}
+
+/**
+ * Report an error through the global handler and console.
+ * Non-throwing — used for recoverable errors in callbacks, lifecycle hooks, etc.
+ *
+ * @param {string} code — ErrorCode
+ * @param {string} message
+ * @param {object} [context]
+ * @param {Error} [cause]
+ */
+export function reportError(code, message, context = {}, cause) {
+  const err = cause instanceof ZQueryError
+    ? cause
+    : new ZQueryError(code, message, context, cause);
+
+  // User handler gets first crack
+  if (_errorHandler) {
+    try { _errorHandler(err); } catch { /* prevent handler from crashing framework */ }
+  }
+
+  // Always log for developer visibility
+  console.error(`[zQuery ${code}] ${message}`, context, cause || '');
+}
+
+/**
+ * Wrap a callback so that thrown errors are caught, reported, and don't crash
+ * the current execution context.
+ *
+ * @param {Function} fn
+ * @param {string} code — ErrorCode to use if the callback throws
+ * @param {object} [context]
+ * @returns {Function}
+ */
+export function guardCallback(fn, code, context = {}) {
+  return (...args) => {
+    try {
+      return fn(...args);
+    } catch (err) {
+      reportError(code, err.message || 'Callback error', context, err);
+    }
+  };
+}
+
+/**
+ * Validate a required value is defined and of the expected type.
+ * Throws ZQueryError on failure (for fast-fail at API boundaries).
+ *
+ * @param {*} value
+ * @param {string} name — parameter name for error message
+ * @param {string} expectedType — 'string', 'function', 'object', etc.
+ */
+export function validate(value, name, expectedType) {
+  if (value === undefined || value === null) {
+    throw new ZQueryError(
+      ErrorCode.INVALID_ARGUMENT,
+      `"${name}" is required but got ${value}`
+    );
+  }
+  if (expectedType && typeof value !== expectedType) {
+    throw new ZQueryError(
+      ErrorCode.INVALID_ARGUMENT,
+      `"${name}" must be a ${expectedType}, got ${typeof value}`
+    );
+  }
+}