zero-query 0.9.8 → 1.0.0

package/src/ssr.js

@@ -1,10 +1,10 @@
 /**
- * zQuery SSR — Server-side rendering to HTML string
+ * zQuery SSR - Server-side rendering to HTML string
  *
  * Renders registered components to static HTML strings for SEO,
  * initial page load performance, and static site generation.
  *
- * Works in Node.js — no DOM required for basic rendering.
+ * Works in Node.js - no DOM required for basic rendering.
  * Supports hydration markers for client-side takeover.
  *
  * Usage (Node.js):
@@ -21,14 +21,7 @@
  */
 
 import { safeEval } from './expression.js';
-
-// ---------------------------------------------------------------------------
-// Minimal reactive proxy for SSR (no scheduling, no DOM)
-// ---------------------------------------------------------------------------
-function ssrReactive(target) {
-  // In SSR, state is plain objects — no Proxy needed since we don't re-render
-  return target;
-}
+import { reportError, ErrorCode, ZQueryError } from './errors.js';
 
 // ---------------------------------------------------------------------------
 // SSR Component renderer
@@ -54,7 +47,14 @@ class SSRComponent {
     if (definition.computed) {
       for (const [name, fn] of Object.entries(definition.computed)) {
         Object.defineProperty(this.computed, name, {
-          get: () => fn.call(this, this.state),
+          get: () => {
+            try {
+              return fn.call(this, this.state);
+            } catch (err) {
+              reportError(ErrorCode.SSR_RENDER, `Computed property "${name}" threw during SSR`, { property: name }, err);
+              return undefined;
+            }
+          },
           enumerable: true
         });
       }
@@ -67,15 +67,26 @@ class SSRComponent {
       }
     }
 
-    // Init
-    if (definition.init) definition.init.call(this);
+    // Init lifecycle - guarded so a broken init doesn't crash the whole render
+    if (definition.init) {
+      try {
+        definition.init.call(this);
+      } catch (err) {
+        reportError(ErrorCode.SSR_RENDER, 'Component init() threw during SSR', {}, err);
+      }
+    }
   }
 
   render() {
     if (this._def.render) {
-      let html = this._def.render.call(this);
-      html = this._interpolate(html);
-      return html;
+      try {
+        let html = this._def.render.call(this);
+        html = this._interpolate(html);
+        return html;
+      } catch (err) {
+        reportError(ErrorCode.SSR_RENDER, 'Component render() threw during SSR', {}, err);
+        return `<!-- SSR render error -->`;
+      }
     }
     return '';
   }
@@ -83,11 +94,16 @@ class SSRComponent {
   // Basic {{expression}} interpolation for SSR
   _interpolate(html) {
     return html.replace(/\{\{(.+?)\}\}/g, (_, expr) => {
-      const result = safeEval(expr.trim(), [
-        this.state,
-        { props: this.props, computed: this.computed }
-      ]);
-      return result != null ? _escapeHtml(String(result)) : '';
+      try {
+        const result = safeEval(expr.trim(), [
+          this.state,
+          { props: this.props, computed: this.computed }
+        ]);
+        return result != null ? _escapeHtml(String(result)) : '';
+      } catch (err) {
+        reportError(ErrorCode.SSR_RENDER, `Expression "{{${expr.trim()}}}" failed during SSR`, { expression: expr.trim() }, err);
+        return '';
+      }
     });
   }
 }
@@ -107,7 +123,7 @@ function _escapeHtml(str) {
 }
 
 // ---------------------------------------------------------------------------
-// SSR App — component registry + renderer
+// SSR App - component registry + renderer
 // ---------------------------------------------------------------------------
 class SSRApp {
   constructor() {
@@ -120,22 +136,44 @@ class SSRApp {
    * @param {object} definition
    */
   component(name, definition) {
+    if (typeof name !== 'string' || !name) {
+      throw new ZQueryError(ErrorCode.SSR_COMPONENT, 'Component name must be a non-empty string');
+    }
+    if (!definition || typeof definition !== 'object') {
+      throw new ZQueryError(ErrorCode.SSR_COMPONENT, `Invalid definition for component "${name}"`);
+    }
     this._registry.set(name, definition);
     return this;
   }
 
+  /**
+   * Check whether a component is registered.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._registry.has(name);
+  }
+
   /**
    * Render a component to an HTML string.
    *
-   * @param {string} componentName — registered component name
-   * @param {object} [props] — props to pass
-   * @param {object} [options] — rendering options
-   * @param {boolean} [options.hydrate=true] — add hydration marker
-   * @returns {Promise<string>} — rendered HTML
+   * @param {string} componentName - registered component name
+   * @param {object} [props] - props to pass
+   * @param {object} [options] - rendering options
+   * @param {boolean} [options.hydrate=true] - add hydration marker
+   * @param {string} [options.mode='html'] - 'html' (default) or 'fragment' (no wrapper tag)
+   * @returns {Promise<string>} - rendered HTML
    */
   async renderToString(componentName, props = {}, options = {}) {
     const def = this._registry.get(componentName);
-    if (!def) throw new Error(`SSR: Component "${componentName}" not registered`);
+    if (!def) {
+      throw new ZQueryError(
+        ErrorCode.SSR_COMPONENT,
+        `SSR: Component "${componentName}" not registered`,
+        { component: componentName }
+      );
+    }
 
     const instance = new SSRComponent(def, props);
     let html = instance.render();
@@ -147,23 +185,43 @@ class SSRApp {
     html = html.replace(/\s*@[\w.]+="[^"]*"/g, ''); // Remove event bindings
     html = html.replace(/\s*z-on:[\w.]+="[^"]*"/g, '');
 
+    // Fragment mode - return inner HTML without wrapper tag
+    if (options.mode === 'fragment') return html;
+
     const hydrate = options.hydrate !== false;
     const marker = hydrate ? ' data-zq-ssr' : '';
 
     return `<${componentName}${marker}>${html}</${componentName}>`;
   }
 
+  /**
+   * Render multiple components as a batch.
+   *
+   * @param {Array<{ name: string, props?: object, options?: object }>} entries
+   * @returns {Promise<string[]>} - array of rendered HTML strings
+   */
+  async renderBatch(entries) {
+    return Promise.all(
+      entries.map(({ name, props, options }) => this.renderToString(name, props, options))
+    );
+  }
+
   /**
    * Render a full HTML page with a component mounted in a shell.
    *
    * @param {object} options
-   * @param {string} options.component — component name to render
-   * @param {object} [options.props] — props
-   * @param {string} [options.title] — page title
-   * @param {string[]} [options.styles] — CSS file paths
-   * @param {string[]} [options.scripts] — JS file paths
-   * @param {string} [options.lang] — html lang attribute
-   * @param {string} [options.meta] — additional head content
+   * @param {string} options.component - component name to render
+   * @param {object} [options.props] - props
+   * @param {string} [options.title] - page title
+   * @param {string} [options.description] - meta description for SEO
+   * @param {string[]} [options.styles] - CSS file paths
+   * @param {string[]} [options.scripts] - JS file paths
+   * @param {string} [options.lang] - html lang attribute
+   * @param {string} [options.meta] - additional head content
+   * @param {string} [options.bodyAttrs] - extra body attributes
+   * @param {object} [options.head] - structured head options
+   * @param {string} [options.head.canonical] - canonical URL
+   * @param {object} [options.head.og] - Open Graph tags
    * @returns {Promise<string>}
    */
   async renderPage(options = {}) {
@@ -171,25 +229,49 @@ class SSRApp {
       component: comp,
       props = {},
       title = '',
+      description = '',
       styles = [],
       scripts = [],
       lang = 'en',
       meta = '',
       bodyAttrs = '',
+      head = {},
     } = options;
 
-    const content = comp ? await this.renderToString(comp, props) : '';
+    let content = '';
+    if (comp) {
+      try {
+        content = await this.renderToString(comp, props);
+      } catch (err) {
+        reportError(ErrorCode.SSR_PAGE, `renderPage failed for component "${comp}"`, { component: comp }, err);
+        content = `<!-- SSR error: ${_escapeHtml(err.message)} -->`;
+      }
+    }
 
     const styleLinks = styles.map(s => `<link rel="stylesheet" href="${_escapeHtml(s)}">`).join('\n    ');
     const scriptTags = scripts.map(s => `<script src="${_escapeHtml(s)}"></script>`).join('\n    ');
 
+    // Build SEO / structured head tags
+    let headExtra = meta;
+    if (description) {
+      headExtra += `\n    <meta name="description" content="${_escapeHtml(description)}">`;
+    }
+    if (head.canonical) {
+      headExtra += `\n    <link rel="canonical" href="${_escapeHtml(head.canonical)}">`;
+    }
+    if (head.og) {
+      for (const [key, val] of Object.entries(head.og)) {
+        headExtra += `\n    <meta property="og:${_escapeHtml(key)}" content="${_escapeHtml(String(val))}">`;
+      }
+    }
+
     return `<!DOCTYPE html>
 <html lang="${_escapeHtml(lang)}">
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>${_escapeHtml(title)}</title>
-    ${meta}
+    ${headExtra}
     ${styleLinks}
   </head>
   <body ${bodyAttrs.replace(/on\w+\s*=/gi, '').replace(/javascript\s*:/gi, '')}>
@@ -214,11 +296,23 @@ export function createSSRApp() {
 
 /**
  * Quick one-shot render of a component definition to string.
- * @param {object} definition — component definition
- * @param {object} [props] — props
+ * @param {object} definition - component definition
+ * @param {object} [props] - props
  * @returns {string}
  */
 export function renderToString(definition, props = {}) {
+  if (!definition || typeof definition !== 'object') {
+    throw new ZQueryError(ErrorCode.SSR_COMPONENT, 'renderToString requires a component definition object');
+  }
   const instance = new SSRComponent(definition, props);
   return instance.render();
 }
+
+/**
+ * Escape HTML entities - exposed for use in SSR templates.
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeHtml(str) {
+  return _escapeHtml(String(str));
+}

package/src/store.js

@@ -1,5 +1,5 @@
 /**
- * zQuery Store — Global reactive state management
+ * zQuery Store - Global reactive state management
  * 
  * A lightweight Redux/Vuex-inspired store with:
  *   - Reactive state via Proxy
@@ -38,22 +38,22 @@ class Store {
     this._history = [];              // action log
     this._maxHistory = config.maxHistory || 1000;
     this._debug = config.debug || false;
+    this._batching = false;
+    this._batchQueue = [];           // pending notifications during batch
+    this._undoStack = [];
+    this._redoStack = [];
+    this._maxUndo = config.maxUndo || 50;
 
-    // Create reactive state
+    // Store initial state for reset
     const initial = typeof config.state === 'function' ? config.state() : { ...(config.state || {}) };
+    this._initialState = JSON.parse(JSON.stringify(initial));
 
     this.state = reactive(initial, (key, value, old) => {
-      // Notify key-specific subscribers
-      const subs = this._subscribers.get(key);
-      if (subs) subs.forEach(fn => {
-        try { fn(value, old, key); }
-        catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, `Subscriber for "${key}" threw`, { key }, err); }
-      });
-      // Notify wildcard subscribers
-      this._wildcards.forEach(fn => {
-        try { fn(key, value, old); }
-        catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, 'Wildcard subscriber threw', { key }, err); }
-      });
+      if (this._batching) {
+        this._batchQueue.push({ key, value, old });
+        return;
+      }
+      this._notifySubscribers(key, value, old);
     });
 
     // Build getters as computed properties
@@ -66,10 +66,90 @@ class Store {
     }
   }
 
+  /** @private Notify key-specific and wildcard subscribers */
+  _notifySubscribers(key, value, old) {
+    const subs = this._subscribers.get(key);
+    if (subs) subs.forEach(fn => {
+      try { fn(key, value, old); }
+      catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, `Subscriber for "${key}" threw`, { key }, err); }
+    });
+    this._wildcards.forEach(fn => {
+      try { fn(key, value, old); }
+      catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, 'Wildcard subscriber threw', { key }, err); }
+    });
+  }
+
+  /**
+   * Batch multiple state changes - subscribers fire once at the end
+   * with only the latest value per key.
+   */
+  batch(fn) {
+    this._batching = true;
+    this._batchQueue = [];
+    try {
+      fn(this.state);
+    } finally {
+      this._batching = false;
+      // Deduplicate: keep only the last change per key
+      const last = new Map();
+      for (const entry of this._batchQueue) {
+        last.set(entry.key, entry);
+      }
+      this._batchQueue = [];
+      for (const { key, value, old } of last.values()) {
+        this._notifySubscribers(key, value, old);
+      }
+    }
+  }
+
+  /**
+   * Save a snapshot for undo. Call before making changes you want to be undoable.
+   */
+  checkpoint() {
+    const snap = JSON.parse(JSON.stringify(this.state.__raw || this.state));
+    this._undoStack.push(snap);
+    if (this._undoStack.length > this._maxUndo) {
+      this._undoStack.splice(0, this._undoStack.length - this._maxUndo);
+    }
+    this._redoStack = [];
+  }
+
+  /**
+   * Undo to the last checkpoint
+   * @returns {boolean} true if undo was performed
+   */
+  undo() {
+    if (this._undoStack.length === 0) return false;
+    const current = JSON.parse(JSON.stringify(this.state.__raw || this.state));
+    this._redoStack.push(current);
+    const prev = this._undoStack.pop();
+    this.replaceState(prev);
+    return true;
+  }
+
+  /**
+   * Redo the last undone state change
+   * @returns {boolean} true if redo was performed
+   */
+  redo() {
+    if (this._redoStack.length === 0) return false;
+    const current = JSON.parse(JSON.stringify(this.state.__raw || this.state));
+    this._undoStack.push(current);
+    const next = this._redoStack.pop();
+    this.replaceState(next);
+    return true;
+  }
+
+  /** Check if undo is available */
+  get canUndo() { return this._undoStack.length > 0; }
+
+  /** Check if redo is available */
+  get canRedo() { return this._redoStack.length > 0; }
+
   /**
    * Dispatch a named action
-   * @param {string} name — action name
-   * @param  {...any} args — payload
+   * @param {string} name - action name
+   * @param  {...any} args - payload
    */
   dispatch(name, ...args) {
     const action = this._actions[name];
@@ -108,13 +188,13 @@ class Store {
 
   /**
    * Subscribe to changes on a specific state key
-   * @param {string|Function} keyOrFn — state key, or function for all changes
-   * @param {Function} [fn] — callback (value, oldValue, key)
-   * @returns {Function} — unsubscribe
+   * @param {string|Function} keyOrFn - state key, or function for all changes
+   * @param {Function} [fn] - callback (key, value, oldValue)
+   * @returns {Function} - unsubscribe
    */
   subscribe(keyOrFn, fn) {
     if (typeof keyOrFn === 'function') {
-      // Wildcard — listen to all changes
+      // Wildcard - listen to all changes
       this._wildcards.add(keyOrFn);
       return () => this._wildcards.delete(keyOrFn);
     }
@@ -160,11 +240,13 @@ class Store {
   }
 
   /**
-   * Reset state to initial values
+   * Reset state to initial values. If no argument, resets to the original state.
    */
   reset(initialState) {
-    this.replaceState(initialState);
+    this.replaceState(initialState || JSON.parse(JSON.stringify(this._initialState)));
     this._history = [];
+    this._undoStack = [];
+    this._redoStack = [];
   }
 }
 

package/src/utils.js

@@ -1,5 +1,5 @@
 /**
- * zQuery Utils — Common utility functions
+ * zQuery Utils - Common utility functions
  * 
  * Quality-of-life helpers that every frontend project needs.
  * Attached to $ namespace for convenience.
@@ -10,7 +10,7 @@
 // ---------------------------------------------------------------------------
 
 /**
- * Debounce — delays execution until after `ms` of inactivity
+ * Debounce - delays execution until after `ms` of inactivity
  */
 export function debounce(fn, ms = 250) {
   let timer;
@@ -23,7 +23,7 @@ export function debounce(fn, ms = 250) {
 }
 
 /**
- * Throttle — limits execution to once per `ms`
+ * Throttle - limits execution to once per `ms`
  */
 export function throttle(fn, ms = 250) {
   let last = 0;
@@ -42,14 +42,14 @@ export function throttle(fn, ms = 250) {
 }
 
 /**
- * Pipe — compose functions left-to-right
+ * Pipe - compose functions left-to-right
  */
 export function pipe(...fns) {
   return (input) => fns.reduce((val, fn) => fn(val), input);
 }
 
 /**
- * Once — function that only runs once
+ * Once - function that only runs once
  */
 export function once(fn) {
   let called = false, result;
@@ -60,7 +60,7 @@ export function once(fn) {
 }
 
 /**
- * Sleep — promise-based delay
+ * Sleep - promise-based delay
  */
 export function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
@@ -111,8 +111,12 @@ export function trust(htmlStr) {
  * Generate UUID v4
  */
 export function uuid() {
-  return crypto?.randomUUID?.() || 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
-    const r = Math.random() * 16 | 0;
+  if (crypto?.randomUUID) return crypto.randomUUID();
+  // Fallback using crypto.getRandomValues (wider support than randomUUID)
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const buf = new Uint8Array(1);
+    crypto.getRandomValues(buf);
+    const r = buf[0] & 15;
     return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
   });
 }
@@ -140,13 +144,50 @@ export function kebabCase(str) {
 // ---------------------------------------------------------------------------
 
 /**
- * Deep clone
+ * Deep clone via structuredClone (handles circular refs, Dates, etc.).
+ * Falls back to a manual deep clone that preserves Date, RegExp, Map, Set,
+ * ArrayBuffer, TypedArrays, undefined values, and circular references.
  */
 export function deepClone(obj) {
   if (typeof structuredClone === 'function') return structuredClone(obj);
-  return JSON.parse(JSON.stringify(obj));
+
+  const seen = new Map();
+  function clone(val) {
+    if (val === null || typeof val !== 'object') return val;
+    if (seen.has(val)) return seen.get(val);
+    if (val instanceof Date) return new Date(val.getTime());
+    if (val instanceof RegExp) return new RegExp(val.source, val.flags);
+    if (val instanceof Map) {
+      const m = new Map();
+      seen.set(val, m);
+      val.forEach((v, k) => m.set(clone(k), clone(v)));
+      return m;
+    }
+    if (val instanceof Set) {
+      const s = new Set();
+      seen.set(val, s);
+      val.forEach(v => s.add(clone(v)));
+      return s;
+    }
+    if (ArrayBuffer.isView(val)) return new val.constructor(val.buffer.slice(0));
+    if (val instanceof ArrayBuffer) return val.slice(0);
+    if (Array.isArray(val)) {
+      const arr = [];
+      seen.set(val, arr);
+      for (let i = 0; i < val.length; i++) arr[i] = clone(val[i]);
+      return arr;
+    }
+    const result = Object.create(Object.getPrototypeOf(val));
+    seen.set(val, result);
+    for (const key of Object.keys(val)) result[key] = clone(val[key]);
+    return result;
+  }
+  return clone(obj);
 }
 
+// Keys that must never be written through data-merge or path-set operations
+const _UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
 /**
  * Deep merge objects
  */
@@ -156,6 +197,7 @@ export function deepMerge(target, ...sources) {
     if (seen.has(src)) return tgt;
     seen.add(src);
     for (const key of Object.keys(src)) {
+      if (_UNSAFE_KEYS.has(key)) continue;
       if (src[key] && typeof src[key] === 'object' && !Array.isArray(src[key])) {
         if (!tgt[key] || typeof tgt[key] !== 'object') tgt[key] = {};
         merge(tgt[key], src[key]);
@@ -362,10 +404,13 @@ export function setPath(obj, path, value) {
   let cur = obj;
   for (let i = 0; i < keys.length - 1; i++) {
     const k = keys[i];
+    if (_UNSAFE_KEYS.has(k)) return obj;
     if (cur[k] == null || typeof cur[k] !== 'object') cur[k] = {};
     cur = cur[k];
   }
-  cur[keys[keys.length - 1]] = value;
+  const lastKey = keys[keys.length - 1];
+  if (_UNSAFE_KEYS.has(lastKey)) return obj;
+  cur[lastKey] = value;
   return obj;
 }
 
@@ -416,9 +461,16 @@ export function memoize(fn, keyFnOrOpts) {
 
   const memoized = (...args) => {
     const key = keyFn ? keyFn(...args) : args[0];
-    if (cache.has(key)) return cache.get(key);
+    if (cache.has(key)) {
+      // LRU: promote to newest by re-inserting
+      const value = cache.get(key);
+      cache.delete(key);
+      cache.set(key, value);
+      return value;
+    }
     const result = fn(...args);
     cache.set(key, result);
+    // LRU eviction: drop the least-recently-used entry
     if (maxSize > 0 && cache.size > maxSize) {
       cache.delete(cache.keys().next().value);
     }