zero-query 0.9.8 → 0.9.9

package/index.js

@@ -27,7 +27,7 @@ import {
   capitalize, truncate, clamp,
   memoize, retry, timeout,
 } from './src/utils.js';
-import { ZQueryError, ErrorCode, onError, reportError, guardCallback, validate } from './src/errors.js';
+import { ZQueryError, ErrorCode, onError, reportError, guardCallback, guardAsync, validate, formatError } from './src/errors.js';
 
 
 // ---------------------------------------------------------------------------
@@ -173,7 +173,9 @@ $.onError        = onError;
 $.ZQueryError    = ZQueryError;
 $.ErrorCode      = ErrorCode;
 $.guardCallback  = guardCallback;
+$.guardAsync     = guardAsync;
 $.validate       = validate;
+$.formatError    = formatError;
 
 // --- Meta ------------------------------------------------------------------
 $.version   = '__VERSION__';
@@ -213,7 +215,7 @@ export {
   createRouter, getRouter,
   createStore, getStore,
   http,
-  ZQueryError, ErrorCode, onError, reportError, guardCallback, validate,
+  ZQueryError, ErrorCode, onError, reportError, guardCallback, guardAsync, validate, formatError,
   debounce, throttle, pipe, once, sleep,
   escapeHtml, stripHtml, html, trust, TrustedHTML, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "zero-query",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Lightweight modern frontend library — jQuery-like selectors, reactive components, SPA router, and state management with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./ssr": "./src/ssr.js",
+    "./src/*": "./src/*"
+  },
   "bin": {
     "zquery": "cli/index.js"
   },
@@ -26,7 +31,8 @@
     "bundle": "node cli/index.js bundle",
     "bundle:app": "node cli/index.js bundle zquery-website",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:ssr": "node scripts/test-ssr.js"
   },
   "keywords": [
     "dom",

package/src/errors.js

@@ -49,6 +49,12 @@ export const ErrorCode = Object.freeze({
   HTTP_INTERCEPTOR:    'ZQ_HTTP_INTERCEPTOR',
   HTTP_PARSE:          'ZQ_HTTP_PARSE',
 
+  // SSR
+  SSR_RENDER:          'ZQ_SSR_RENDER',
+  SSR_COMPONENT:       'ZQ_SSR_COMPONENT',
+  SSR_HYDRATION:       'ZQ_SSR_HYDRATION',
+  SSR_PAGE:            'ZQ_SSR_PAGE',
+
   // General
   INVALID_ARGUMENT:    'ZQ_INVALID_ARGUMENT',
 });
@@ -77,16 +83,28 @@ export class ZQueryError extends Error {
 // ---------------------------------------------------------------------------
 // Global error handler
 // ---------------------------------------------------------------------------
-let _errorHandler = null;
+let _errorHandlers = [];
 
 /**
  * Register a global error handler.
  * Called whenever zQuery catches an error internally.
+ * Multiple handlers are supported — each receives the error.
+ * Pass `null` to clear all handlers.
  *
  * @param {Function|null} handler — (error: ZQueryError) => void
+ * @returns {Function} unsubscribe function to remove this handler
  */
 export function onError(handler) {
-  _errorHandler = typeof handler === 'function' ? handler : null;
+  if (handler === null) {
+    _errorHandlers = [];
+    return () => {};
+  }
+  if (typeof handler !== 'function') return () => {};
+  _errorHandlers.push(handler);
+  return () => {
+    const idx = _errorHandlers.indexOf(handler);
+    if (idx !== -1) _errorHandlers.splice(idx, 1);
+  };
 }
 
 /**
@@ -103,9 +121,9 @@ export function reportError(code, message, context = {}, cause) {
     ? cause
     : new ZQueryError(code, message, context, cause);
 
-  // User handler gets first crack
-  if (_errorHandler) {
-    try { _errorHandler(err); } catch { /* prevent handler from crashing framework */ }
+  // Notify all registered handlers
+  for (const handler of _errorHandlers) {
+    try { handler(err); } catch { /* prevent handler from crashing framework */ }
   }
 
   // Always log for developer visibility
@@ -153,3 +171,39 @@ export function validate(value, name, expectedType) {
     );
   }
 }
+
+/**
+ * Format a ZQueryError into a structured object suitable for overlays/logging.
+ * @param {ZQueryError|Error} err
+ * @returns {{ code: string, type: string, message: string, context: object, stack: string }}
+ */
+export function formatError(err) {
+  const isZQ = err instanceof ZQueryError;
+  return {
+    code: isZQ ? err.code : '',
+    type: isZQ ? 'ZQueryError' : (err.name || 'Error'),
+    message: err.message || 'Unknown error',
+    context: isZQ ? err.context : {},
+    stack: err.stack || '',
+    cause: err.cause ? formatError(err.cause) : null,
+  };
+}
+
+/**
+ * Async version of guardCallback — wraps an async function so that
+ * rejections are caught, reported, and don't crash execution.
+ *
+ * @param {Function} fn — async function
+ * @param {string} code — ErrorCode to use
+ * @param {object} [context]
+ * @returns {Function}
+ */
+export function guardAsync(fn, code, context = {}) {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (err) {
+      reportError(code, err.message || 'Async callback error', context, err);
+    }
+  };
+}

package/src/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/src/ssr.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: ${_escapeHtml(err.message)} -->`;
+      }
     }
     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 '';
+      }
     });
   }
 }
@@ -120,10 +136,25 @@ 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.
    *
@@ -131,11 +162,18 @@ class SSRApp {
    * @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,12 +185,27 @@ 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.
    *
@@ -160,10 +213,15 @@ class SSRApp {
    * @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, '')}>
@@ -219,6 +301,18 @@ export function createSSRApp() {
  * @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));
+}