zero-query 1.0.2 → 1.0.9

package/README.md

@@ -15,7 +15,7 @@
 
 </p>
 
-> **Lightweight, zero-dependency frontend library that combines jQuery-style DOM manipulation with a modern reactive component system, SPA router, global state management, HTTP client, and utility toolkit - all in a single ~91 KB minified browser bundle. Works out of the box with ES modules. An optional CLI bundler is available for single-file production builds.**
+> **Lightweight, zero-dependency frontend library that combines jQuery-style DOM manipulation with a modern reactive component system, SPA router, global state management, HTTP client, and utility toolkit - all in a single ~108 KB minified browser bundle. Works out of the box with ES modules. An optional CLI bundler is available for single-file production builds.**
 
 ## Features
 
@@ -29,9 +29,9 @@
 | **Selectors & DOM** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
 | **HTTP** | Fetch wrapper with auto-JSON, interceptors (with unsubscribe & clear), HEAD requests, parallel requests (`http.all`), config inspection (`getConfig`), timeout/abort, base URL |
 | **Utils** | debounce, throttle, pipe, once, sleep, memoize (LRU), escapeHtml, stripHtml, uuid, capitalize, truncate, range, chunk, groupBy, unique, pick, omit, getPath/setPath, isEmpty, clamp, retry, timeout, deepClone (enhanced fallback), deepMerge (prototype-pollution safe), storage/session wrappers, event bus |
-| **Security** | XSS-safe template expressions (`{{}}` auto-escaping), sandboxed expression evaluator (blocks `window`, `Function`, `eval`, `RegExp`, `Error`, prototype chains), prototype pollution prevention in `deepMerge`/`setPath`, `z-link` protocol validation, SSR error sanitization |
+| **Security** | XSS-safe template expressions (`{{}}` auto-escaping), sandboxed expression evaluator (blocks `window`, `Function`, `eval`, `RegExp`, `Error`, prototype chains), prototype pollution prevention in `deepMerge`/`setPath`, `z-link` protocol validation, SSR error sanitization, `renderShell()` metadata injection hardening (script-tag breakout prevention, ReDoS-safe OG keys, safe `.replace()` patterns) |
 | **Dev Tools** | CLI dev server with live-reload, CSS hot-swap, full-screen error overlay, floating toolbar, dark-themed inspector panel (Router view, DOM tree, network log, component viewer, performance dashboard), fetch interceptor, render instrumentation, CLI bundler for single-file production builds |
-| **SSR** | Server-side rendering to HTML strings in Node.js - `createSSRApp()`, `renderToString()`, `renderPage()` with SEO/Open Graph support, `renderBatch()` for parallel rendering, fragment mode, hydration markers, graceful error handling, `escapeHtml()` utility |
+| **SSR** | Server-side rendering to HTML strings in Node.js - `createSSRApp()`, `renderToString()`, `renderPage()` with SEO/Open Graph support, `renderShell()` for injecting SSR into custom HTML shells, `renderBatch()` for parallel rendering, fragment mode, hydration markers, graceful error handling, `escapeHtml()` utility |
 
 ---
 
@@ -43,7 +43,7 @@ The fastest way to develop with zQuery is via the built-in **CLI dev server** wi
 
 ```bash
 # Install (per-project or globally)
-npm install zero-query --save-dev   # or: npm install zero-query -g
+npm install zero-query   # or: npm install zero-query -g
 ```
 
 Scaffold a new project and start the server:
@@ -77,7 +77,7 @@ If you prefer **zero tooling**, download `dist/zquery.min.js` from the [dist/ fo
 git clone https://github.com/tonywied17/zero-query.git
 cd zero-query
 npx zquery build
-# → dist/zquery.min.js  (~91 KB)
+# → dist/zquery.min.js  (~108 KB)
 ```
 
 ### Include in HTML
@@ -363,7 +363,7 @@ $.router({ base: '/my-app', routes });
 | `$.storage` `$.session` | Storage wrappers |
 | `$.EventBus` `$.bus` | Event bus |
 | `$.onError` `$.ZQueryError` `$.ErrorCode` `$.guardCallback` `$.guardAsync` `$.formatError` `$.validate` | Error handling |
-| `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~91 KB\"`) |
+| `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~108 KB\"`) |
 | `$.unitTests` | Build-time test results `{ passed, failed, total, suites, duration, ok }` |
 | `$.meta` | Build metadata (populated by CLI bundler) |
 | `$.noConflict` | Release `$` global |

package/cli/commands/bundle.js

@@ -87,14 +87,137 @@ function walkImportGraph(entry) {
   return order;
 }
 
-/** Strip ES module import/export syntax, keeping declarations. */
+/**
+ * Strip ES module import/export syntax, keeping declarations.
+ * Exported const/let are converted to var so they hoist past the per-module
+ * block scope and remain accessible to downstream modules.
+ * Exported function/class are converted to var assignments for the same reason.
+ * Non-exported declarations stay as-is and remain block-scoped (private).
+ *
+ * Template literals are temporarily hidden via a character-level scanner
+ * (handles nested backtick expressions) so that code examples inside
+ * backtick strings aren't accidentally rewritten.
+ */
 function stripModuleSyntax(code) {
+  // -- Hide template literals (supports nesting) -------------------------
+  const templates = [];
+
+  function scanTemplateLiteral(str, start) {
+    let i = start + 1; // skip opening backtick
+    while (i < str.length) {
+      const ch = str[i];
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === '`')  { return i + 1; }          // end of template
+      if (ch === '$' && str[i + 1] === '{') {
+        i += 2;                                    // skip ${
+        let depth = 1;
+        while (i < str.length && depth > 0) {
+          const c = str[i];
+          if (c === '{') { depth++; i++; }
+          else if (c === '}') { depth--; i++; }
+          else if (c === '`') { i = scanTemplateLiteral(str, i); }
+          else if (c === "'" || c === '"') { i = skipString(str, i); }
+          else if (c === '/' && str[i + 1] === '/') { while (i < str.length && str[i] !== '\n') i++; }
+          else if (c === '/' && str[i + 1] === '*') { i += 2; while (i < str.length - 1 && !(str[i] === '*' && str[i + 1] === '/')) i++; i += 2; }
+          else { i++; }
+        }
+        continue;
+      }
+      i++;
+    }
+    return i;
+  }
+
+  function skipString(str, start) {
+    const q = str[start];
+    let i = start + 1;
+    while (i < str.length) {
+      if (str[i] === '\\') { i += 2; continue; }
+      if (str[i] === q)    { return i + 1; }
+      i++;
+    }
+    return i;
+  }
+
+  let hidden = '';
+  let pos = 0;
+  while (pos < code.length) {
+    const ch = code[pos];
+    if (ch === "'" || ch === '"') {
+      const end = skipString(code, pos);
+      hidden += code.substring(pos, end);
+      pos = end;
+    } else if (ch === '/' && code[pos + 1] === '/') {
+      let end = pos;
+      while (end < code.length && code[end] !== '\n') end++;
+      hidden += code.substring(pos, end);
+      pos = end;
+    } else if (ch === '/' && code[pos + 1] === '*') {
+      let end = pos + 2;
+      while (end < code.length - 1 && !(code[end] === '*' && code[end + 1] === '/')) end++;
+      end += 2;
+      hidden += code.substring(pos, end);
+      pos = end;
+    } else if (ch === '`') {
+      const end = scanTemplateLiteral(code, pos);
+      templates.push(code.substring(pos, end));
+      hidden += `__TPL_${templates.length - 1}__`;
+      pos = end;
+    } else {
+      hidden += ch;
+      pos++;
+    }
+  }
+
+  // -- Apply import / export transforms -----------------------------------
+  code = hidden;
   code = code.replace(/^\s*import\s+[\s\S]*?from\s+['"].*?['"];?\s*$/gm, '');
   code = code.replace(/^\s*import\s+['"].*?['"];?\s*$/gm, '');
   code = code.replace(/^(\s*)export\s+default\s+/gm, '$1');
-  code = code.replace(/^(\s*)export\s+(const|let|var|function|class|async\s+function)\s/gm, '$1$2 ');
-  code = code.replace(/^\s*export\s*\{[\s\S]*?\};?\s*$/gm, '');
-  return code;
+  // Convert exported const/let/var to var (hoists past block scope)
+  code = code.replace(/^(\s*)export\s+(const|let|var)\s/gm, '$1var ');
+  // Convert exported function/async function to var assignment (hoists past block scope)
+  code = code.replace(/^(\s*)export\s+async\s+function\s+(\w+)/gm, '$1var $2 = async function $2');
+  code = code.replace(/^(\s*)export\s+function\s+(\w+)/gm, '$1var $2 = function $2');
+  // Convert exported class to var assignment
+  code = code.replace(/^(\s*)export\s+class\s+(\w+)/gm, '$1var $2 = class $2');
+  // Collect names from bare export blocks: export { a, b, c };
+  // These names are declared elsewhere (function/const/let) and need to be
+  // hoisted past the per-module block scope.  We collect them here and
+  // the caller converts their declarations to var-based forms.
+  const bareExportNames = [];
+  code = code.replace(/^\s*export\s*\{([^}]+)\};?\s*$/gm, (_, names) => {
+    for (const n of names.split(',')) {
+      const parts = n.trim().split(/\s+as\s+/);
+      if (parts[0]) bareExportNames.push({ local: parts[0].trim(), exported: (parts[1] || parts[0]).trim() });
+    }
+    return '';
+  });
+
+  // For every bare-exported name, convert its block-scoped declaration to a
+  // var-based form so it hoists past the per-module { } wrapper:
+  //   function foo(…) { … }  →  var foo = function foo(…) { … }
+  //   async function foo(…)  →  var foo = async function foo(…)
+  //   const/let foo = …      →  var foo = …
+  for (const { local } of bareExportNames) {
+    const fnRe = new RegExp(`^(\\s*)function\\s+${local}\\s*\\(`, 'gm');
+    code = code.replace(fnRe, `$1var ${local} = function ${local}(`);
+    const asyncFnRe = new RegExp(`^(\\s*)async\\s+function\\s+${local}\\s*\\(`, 'gm');
+    code = code.replace(asyncFnRe, `$1var ${local} = async function ${local}(`);
+    const constLetRe = new RegExp(`^(\\s*)(const|let)\\s+${local}\\b`, 'gm');
+    code = code.replace(constLetRe, `$1var ${local}`);
+  }
+
+  // Create aliases for "export { local as exported }" where the names differ
+  for (const { local, exported } of bareExportNames) {
+    if (exported !== local) {
+      code += `\nvar ${exported} = ${local};`;
+    }
+  }
+
+  // -- Restore template literals ------------------------------------------
+  code = code.replace(/__TPL_(\d+)__/g, (_, i) => templates[i]);
+  return { code, bareExportNames };
 }
 
 /** Replace import.meta.url with a runtime equivalent. */
@@ -381,8 +504,8 @@ function collectInlineResources(files, projectRoot) {
 
     // styleUrl:
     const styleUrlRe = /styleUrl\s*:\s*['"]([^'"]+)['"]/g;
-    const styleMatch = styleUrlRe.exec(code);
-    if (styleMatch) {
+    let styleMatch;
+    while ((styleMatch = styleUrlRe.exec(code)) !== null) {
       const stylePath = path.join(fileDir, styleMatch[1]);
       if (fs.existsSync(stylePath)) {
         const relKey = path.relative(projectRoot, stylePath).replace(/\\/g, '/');
@@ -877,12 +1000,13 @@ function bundleApp() {
 
   const sections = files.map(file => {
     let code = fs.readFileSync(file, 'utf-8');
-    code = stripModuleSyntax(code);
+    const stripped = stripModuleSyntax(code);
+    code = stripped.code;
     code = replaceImportMeta(code, file, projectRoot);
     code = rewriteResourceUrls(code, file, projectRoot);
     code = minifyTemplateLiterals(code);
     const rel = path.relative(projectRoot, file);
-    return `// --- ${rel} ${'-'.repeat(Math.max(1, 60 - rel.length))}\n${code.trim()}`;
+    return `// --- ${rel} ${'-'.repeat(Math.max(1, 60 - rel.length))}\n{\n${code.trim()}\n}`;
   });
 
   // Embed zquery.min.js
@@ -1056,3 +1180,4 @@ function bundleApp() {
 }
 
 module.exports = bundleApp;
+module.exports.stripModuleSyntax = stripModuleSyntax;

package/cli/commands/dev/server.js

@@ -92,7 +92,8 @@ async function createServer({ root, htmlEntry, port, noIntercept }) {
     zeroHttp = require('zero-http');
   }
 
-  const { createApp, static: serveStatic } = zeroHttp;
+  const { createApp, static: serveStatic, debug } = zeroHttp;
+  debug.level('silent');
 
   const app  = createApp();
   const pool = new SSEPool();

package/cli/scaffold/ssr/app/app.js

@@ -35,7 +35,7 @@ const router = $.router({
 });
 
 // Update document.title on client-side navigations
-router.onChange(({ component }) => {
-  const title = routeTitles[component];
+router.onChange(({ route }) => {
+  const title = routeTitles[route.component];
   if (title) document.title = title;
 });

package/cli/scaffold/ssr/app/components/blog/post.js

@@ -34,6 +34,7 @@ export const blogPost = {
     if (ssrData && ssrData.component === 'blog-post' && ssrData.params.slug === slug) {
       this.state.post = ssrData.props.post;
       this.state.loaded = true;
+      if (ssrData.meta && ssrData.meta.title) document.title = ssrData.meta.title;
       window.__SSR_DATA__ = null;
       return;
     }
@@ -44,6 +45,13 @@ export const blogPost = {
       this.state.post = await res.json();
     }
     this.state.loaded = true;
+
+    // Update page title for client-side navigations
+    if (this.state.post) {
+      document.title = `${this.state.post.title} — {{NAME}}`;
+    } else {
+      document.title = 'Post Not Found — {{NAME}}';
+    }
   },
 
   render() {

package/cli/scaffold/ssr/server/index.js

@@ -12,7 +12,7 @@ import { createServer } from 'node:http';
 import { readFile } from 'node:fs/promises';
 import { join, extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createSSRApp } from 'zero-query/ssr';
+import { createSSRApp, matchRoute } from 'zero-query/ssr';
 
 // Shared component definitions - same ones the client registers
 import { homePage }  from '../app/components/home.js';
@@ -38,29 +38,6 @@ app.component('blog-list',  blogList);
 app.component('blog-post',  blogPost);
 app.component('not-found',  notFound);
 
-// --- Route matching ---------------------------------------------------------
-
-/**
- * Match a pathname to a route definition. Supports :param segments.
- * Returns { component, params } or the not-found fallback.
- */
-function matchRoute(pathname) {
-  for (const route of routes) {
-    const paramNames = [];
-    const pattern = route.path.replace(/:(\w+)/g, (_, name) => {
-      paramNames.push(name);
-      return '([^/]+)';
-    });
-    const match = new RegExp(`^${pattern}$`).exec(pathname);
-    if (match) {
-      const params = {};
-      paramNames.forEach((name, i) => { params[name] = match[i + 1]; });
-      return { component: route.component, params };
-    }
-  }
-  return { component: 'not-found', params: {} };
-}
-
 // --- Server-side data fetching ----------------------------------------------
 
 /**
@@ -141,7 +118,7 @@ function getMetaForRoute(component, params, props) {
 
 // Read the index.html shell once at startup — it already has z-link nav,
 // client scripts (zquery.min.js + app/app.js), and the <z-outlet> tag.
-// On each request we just inject the SSR body into <z-outlet>.
+// On each request we render the matched component into the shell.
 let shellCache = null;
 async function getShell() {
   if (!shellCache) shellCache = await readFile(join(ROOT, 'index.html'), 'utf-8');
@@ -149,45 +126,22 @@ async function getShell() {
 }
 
 async function render(pathname) {
-  const { component, params } = matchRoute(pathname);
+  const { component, params } = matchRoute(routes, pathname);
   const props = getPropsForRoute(component, params);
   const meta = getMetaForRoute(component, params, props);
 
-  // SSR render — pass server-fetched data as props to the component
-  const body = await app.renderToString(component, props);
-  const shell = await getShell();
-
-  // Inject SSR content into <z-outlet …>
-  let html = shell.replace(/(<z-outlet[^>]*>)(<\/z-outlet>)?/, `$1${body}</z-outlet>`);
-
-  // Inject page-specific <title> and meta tags for SEO / social sharing
-  html = html.replace(/<title>[^<]*<\/title>/, `<title>${meta.title}</title>`);
-  html = html.replace(
-    /<meta name="description" content="[^"]*">/,
-    `<meta name="description" content="${meta.description}">`
-  );
-  html = html.replace(
-    /<meta property="og:title" content="[^"]*">/,
-    `<meta property="og:title" content="${meta.title}">`
-  );
-  html = html.replace(
-    /<meta property="og:description" content="[^"]*">/,
-    `<meta property="og:description" content="${meta.description}">`
-  );
-  html = html.replace(
-    /<meta property="og:type" content="[^"]*">/,
-    `<meta property="og:type" content="${meta.ogType}">`
-  );
-
-  // Embed server data so the client can hydrate without re-fetching.
-  // Also include meta so client can update document.title on navigation.
-  const ssrData = JSON.stringify({ component, params, props, meta });
-  html = html.replace(
-    '</head>',
-    `<script>window.__SSR_DATA__=${ssrData};</script>\n</head>`
-  );
-
-  return html;
+  return app.renderShell(await getShell(), {
+    component,
+    props,
+    title: meta.title,
+    description: meta.description,
+    og: {
+      title: meta.title,
+      description: meta.description,
+      type: meta.ogType,
+    },
+    ssrData: { component, params, props, meta },
+  });
 }
 
 // --- Static files -----------------------------------------------------------

package/cli/utils.js

@@ -206,9 +206,18 @@ function _minifyBody(code) {
 
     // ── Whitespace: collapse ────────────────────────────────────
     if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
-      while (i < code.length && (code[i] === ' ' || code[i] === '\t' || code[i] === '\n' || code[i] === '\r')) i++;
+      let hasNewline = ch === '\n' || ch === '\r';
+      while (i < code.length && (code[i] === ' ' || code[i] === '\t' || code[i] === '\n' || code[i] === '\r')) {
+        if (code[i] === '\n' || code[i] === '\r') hasNewline = true;
+        i++;
+      }
       const before = out[out.length - 1];
       const after  = code[i];
+      // After '}', a newline may be needed for ASI (e.g. var x=function(){}⏎var y).
+      // A space alone doesn't trigger ASI, so preserve ';\n' when '}' precedes
+      // an identifier-start character and the original whitespace had a newline.
+      const afterIsId = after && ((after >= 'a' && after <= 'z') || (after >= 'A' && after <= 'Z') || after === '_' || after === '$');
+      if (before === '}' && afterIsId && hasNewline) { out += '\n'; continue; }
       if (_needsSpace(before, after)) out += ' ';
       continue;
     }

package/dist/zquery.js

@@ -1,5 +1,5 @@
 /**
- * zQuery (zeroQuery) v1.0.2
+ * zQuery (zeroQuery) v1.0.9
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman - MIT License
@@ -4470,24 +4470,15 @@ class Router {
 
   add(route) {
     // Compile path pattern into regex
-    const keys = [];
-    const pattern = route.path
-      .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; })
-      .replace(/\*/g, '(.*)');
-    const regex = new RegExp(`^${pattern}$`);
-
+    const { regex, keys } = compilePath(route.path);
     this._routes.push({ ...route, _regex: regex, _keys: keys });
 
     // Per-route fallback: register an alias path for the same component.
     // e.g. { path: '/docs/:section', fallback: '/docs', component: 'docs-page' }
     // When matched via fallback, missing params are undefined.
     if (route.fallback) {
-      const fbKeys = [];
-      const fbPattern = route.fallback
-        .replace(/:(\w+)/g, (_, key) => { fbKeys.push(key); return '([^/]+)'; })
-        .replace(/\*/g, '(.*)');
-      const fbRegex = new RegExp(`^${fbPattern}$`);
-      this._routes.push({ ...route, path: route.fallback, _regex: fbRegex, _keys: fbKeys });
+      const fb = compilePath(route.fallback);
+      this._routes.push({ ...route, path: route.fallback, _regex: fb.regex, _keys: fb.keys });
     }
 
     return this;
@@ -4984,6 +4975,64 @@ class Router {
 }
 
 
+// ---------------------------------------------------------------------------
+// Path compilation (shared by Router.add and matchRoute)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a route path pattern into a RegExp and param key list.
+ * Supports `:param` segments and `*` wildcard.
+ * @param {string} path - e.g. '/user/:id' or '/files/*'
+ * @returns {{ regex: RegExp, keys: string[] }}
+ */
+function compilePath(path) {
+  const keys = [];
+  const pattern = path
+    .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; })
+    .replace(/\*/g, '(.*)');
+  return { regex: new RegExp(`^${pattern}$`), keys };
+}
+
+// ---------------------------------------------------------------------------
+// Standalone route matcher (DOM-free — usable on server and client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a pathname against an array of route definitions.
+ * Returns `{ component, params }`.  If no route matches, falls back to the
+ * `fallback` component name (default `'not-found'`).
+ *
+ * This is the same matching logic the client-side router uses internally,
+ * extracted so SSR servers can resolve URLs without the DOM.
+ *
+ * @param {Array<{ path: string, component: string, fallback?: string }>} routes
+ * @param {string} pathname - URL path to match, e.g. '/blog/my-post'
+ * @param {string} [fallback='not-found'] - Component name when nothing matches
+ * @returns {{ component: string, params: Record<string, string> }}
+ */
+function matchRoute(routes, pathname, fallback = 'not-found') {
+  for (const route of routes) {
+    const { regex, keys } = compilePath(route.path);
+    const m = pathname.match(regex);
+    if (m) {
+      const params = {};
+      keys.forEach((key, i) => { params[key] = m[i + 1]; });
+      return { component: route.component, params };
+    }
+    // Per-route fallback alias (same as Router.add)
+    if (route.fallback) {
+      const fb = compilePath(route.fallback);
+      const fbm = pathname.match(fb.regex);
+      if (fbm) {
+        const params = {};
+        fb.keys.forEach((key, i) => { params[key] = fbm[i + 1]; });
+        return { component: route.component, params };
+      }
+    }
+  }
+  return { component: fallback, params: {} };
+}
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -6139,8 +6188,9 @@ $.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
-$.router    = createRouter;
-$.getRouter = getRouter;
+$.router     = createRouter;
+$.getRouter  = getRouter;
+$.matchRoute = matchRoute;
 
 // --- Store -----------------------------------------------------------------
 $.store    = createStore;
@@ -6204,9 +6254,9 @@ $.validate       = validate;
 $.formatError    = formatError;
 
 // --- Meta ------------------------------------------------------------------
-$.version   = '1.0.2';
-$.libSize   = '~107 KB';
-$.unitTests = {"passed":1906,"failed":0,"total":1906,"suites":521,"duration":3744,"ok":true};
+$.version   = '1.0.9';
+$.libSize   = '~108 KB';
+$.unitTests = {"passed":1965,"failed":0,"total":1965,"suites":525,"duration":3752,"ok":true};
 $.meta      = {};              // populated at build time by CLI bundler
 
 $.noConflict = () => {