zero-query 1.0.2 → 1.0.9

package/index.d.ts

@@ -4,7 +4,7 @@
  * Lightweight modern frontend library - jQuery-like selectors, reactive
  * components, SPA router, state management, HTTP client & utilities.
  *
- * @version 1.0.2
+ * @version 1.0.9
  * @license MIT
  * @see https://z-query.com/docs
  */
@@ -46,8 +46,10 @@ export {
   NavigationContext,
   RouterConfig,
   RouterInstance,
+  RouteMatch,
   createRouter,
   getRouter,
+  matchRoute,
 } from './types/router';
 
 export {
@@ -146,7 +148,7 @@ export {
 import type { ZQueryCollection } from './types/collection';
 import type { reactive, Signal, signal, computed, effect, batch, untracked } from './types/reactive';
 import type { component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style } from './types/component';
-import type { createRouter, getRouter } from './types/router';
+import type { createRouter, getRouter, matchRoute } from './types/router';
 import type { createStore, getStore } from './types/store';
 import type { HttpClient } from './types/http';
 import type {
@@ -264,6 +266,7 @@ interface ZQueryStatic {
   // -- Router --------------------------------------------------------------
   router: typeof createRouter;
   getRouter: typeof getRouter;
+  matchRoute: typeof matchRoute;
 
   // -- Store ---------------------------------------------------------------
   store: typeof createStore;

package/index.js

@@ -12,7 +12,7 @@
 import { query, queryAll, ZQueryCollection } from './src/core.js';
 import { reactive, Signal, signal, computed, effect, batch, untracked } from './src/reactive.js';
 import { component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style } from './src/component.js';
-import { createRouter, getRouter } from './src/router.js';
+import { createRouter, getRouter, matchRoute } from './src/router.js';
 import { createStore, getStore } from './src/store.js';
 import { http } from './src/http.js';
 import { morph, morphElement } from './src/diff.js';
@@ -115,8 +115,9 @@ $.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
-$.router    = createRouter;
-$.getRouter = getRouter;
+$.router     = createRouter;
+$.getRouter  = getRouter;
+$.matchRoute = matchRoute;
 
 // --- Store -----------------------------------------------------------------
 $.store    = createStore;
@@ -214,7 +215,7 @@ export {
   component, mount, mountAll, getInstance, destroy, getRegistry, prefetch, style,
   morph, morphElement,
   safeEval,
-  createRouter, getRouter,
+  createRouter, getRouter, matchRoute,
   createStore, getStore,
   http,
   ZQueryError, ErrorCode, onError, reportError, guardCallback, guardAsync, validate, formatError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "1.0.2",
+  "version": "1.0.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",
@@ -64,6 +64,6 @@
   "devDependencies": {
     "jsdom": "^28.1.0",
     "vitest": "^4.0.18",
-    "zero-http": "^0.2.3"
+    "zero-http": "^0.3.5"
   }
 }

package/src/router.js

@@ -195,24 +195,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;
@@ -709,6 +700,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> }}
+ */
+export 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
 // ---------------------------------------------------------------------------

package/src/ssr.js

@@ -280,6 +280,103 @@ class SSRApp {
   </body>
 </html>`;
   }
+
+  /**
+   * Render a component into an existing HTML shell template.
+   *
+   * Unlike renderPage() which generates a full HTML document from scratch,
+   * renderShell() takes your own index.html (with nav, footer, custom markup)
+   * and injects the SSR-rendered component body plus metadata into it.
+   *
+   * Handles:
+   *   - Component rendering into <z-outlet>
+   *   - <title> replacement
+   *   - <meta name="description"> replacement
+   *   - Open Graph meta tag replacement (og:title, og:description, og:type, etc.)
+   *   - window.__SSR_DATA__ hydration script injection
+   *
+   * @param {string} shell - HTML template string (your index.html)
+   * @param {object} options
+   * @param {string} options.component - registered component name to render
+   * @param {object} [options.props] - props passed to the component
+   * @param {string} [options.title] - page title (replaces <title>)
+   * @param {string} [options.description] - meta description (replaces <meta name="description">)
+   * @param {object} [options.og] - Open Graph tags to replace (e.g. { title, description, type, image })
+   * @param {any}    [options.ssrData] - data to embed as window.__SSR_DATA__ for client hydration
+   * @param {object} [options.renderOptions] - options passed to renderToString (hydrate, mode)
+   * @returns {Promise<string>} - the shell with SSR content and metadata injected
+   */
+  async renderShell(shell, options = {}) {
+    const {
+      component: comp,
+      props = {},
+      title,
+      description,
+      og,
+      ssrData,
+      renderOptions,
+    } = options;
+
+    // Render the component
+    let body = '';
+    if (comp) {
+      try {
+        body = await this.renderToString(comp, props, renderOptions);
+      } catch (err) {
+        reportError(ErrorCode.SSR_PAGE, `renderShell failed for component "${comp}"`, { component: comp }, err);
+        body = `<!-- SSR error: ${_escapeHtml(err.message)} -->`;
+      }
+    }
+
+    let html = shell;
+
+    // Inject SSR body into <z-outlet>
+    // Use a replacer function to avoid $ substitution patterns in body
+    html = html.replace(/(<z-outlet[^>]*>)([\s\S]*?)(<\/z-outlet>)?/, (_, open) => `${open}${body}</z-outlet>`);
+
+    // Replace <title>
+    if (title != null) {
+      const safeTitle = _escapeHtml(title);
+      html = html.replace(/<title>[^<]*<\/title>/, () => `<title>${safeTitle}</title>`);
+    }
+
+    // Replace <meta name="description">
+    if (description != null) {
+      const safeDesc = _escapeHtml(description);
+      html = html.replace(
+        /<meta\s+name="description"\s+content="[^"]*">/,
+        () => `<meta name="description" content="${safeDesc}">`
+      );
+    }
+
+    // Replace Open Graph meta tags
+    if (og) {
+      for (const [key, value] of Object.entries(og)) {
+        // Sanitize key: allow only safe OG property characters (alphanumeric, hyphens, underscores, colons)
+        const safeKey = key.replace(/[^a-zA-Z0-9_:\-]/g, '');
+        if (!safeKey) continue;
+        const escaped = _escapeHtml(String(value));
+        // Escape key for use in RegExp to prevent ReDoS
+        const escapedKey = safeKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`<meta\\s+property="og:${escapedKey}"\\s+content="[^"]*">`);
+        if (pattern.test(html)) {
+          html = html.replace(pattern, () => `<meta property="og:${safeKey}" content="${escaped}">`);
+        } else {
+          // Tag doesn't exist — inject before </head>
+          html = html.replace('</head>', () => `<meta property="og:${safeKey}" content="${escaped}">\n</head>`);
+        }
+      }
+    }
+
+    // Inject hydration data as window.__SSR_DATA__
+    if (ssrData !== undefined) {
+      // Escape </script> and <!-- sequences to prevent breaking out of the script tag
+      const json = JSON.stringify(ssrData).replace(/<\//g, '<\\/').replace(/<!--/g, '<\\!--');
+      html = html.replace('</head>', () => `<script>window.__SSR_DATA__=${json};</script>\n</head>`);
+    }
+
+    return html;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -316,3 +413,6 @@ export function renderToString(definition, props = {}) {
 export function escapeHtml(str) {
   return _escapeHtml(String(str));
 }
+
+// Re-export matchRoute so SSR servers can import from 'zero-query/ssr'
+export { matchRoute } from './router.js';

package/tests/cli.test.js

@@ -1,6 +1,269 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 
 
+// ---------------------------------------------------------------------------
+// CLI bundle - stripModuleSyntax
+// ---------------------------------------------------------------------------
+
+describe('CLI - stripModuleSyntax', () => {
+  let stripModuleSyntax;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const mod = await import('../cli/commands/bundle.js');
+    stripModuleSyntax = mod.stripModuleSyntax;
+  });
+
+  // -- Import stripping ---------------------------------------------------
+
+  it('strips named import from module', () => {
+    const result = stripModuleSyntax("import { foo } from './mod.js';\nconst x = 1;");
+    expect(result.code.trim()).toBe('const x = 1;');
+  });
+
+  it('strips default import from module', () => {
+    const result = stripModuleSyntax("import foo from './mod.js';\nconst x = 1;");
+    expect(result.code.trim()).toBe('const x = 1;');
+  });
+
+  it('strips side-effect import', () => {
+    const result = stripModuleSyntax("import './mod.js';\nconst x = 1;");
+    expect(result.code.trim()).toBe('const x = 1;');
+  });
+
+  it('strips multi-line import', () => {
+    const input = "import {\n  a,\n  b,\n  c\n} from './mod.js';\nconst x = 1;";
+    const result = stripModuleSyntax(input);
+    expect(result.code.trim()).toBe('const x = 1;');
+  });
+
+  // -- export default -----------------------------------------------------
+
+  it('strips export default keyword', () => {
+    const result = stripModuleSyntax('export default function foo() {}');
+    expect(result.code.trim()).toBe('function foo() {}');
+  });
+
+  // -- export const/let/var → var -----------------------------------------
+
+  it('converts export const to var', () => {
+    const result = stripModuleSyntax('export const x = 1;');
+    expect(result.code.trim()).toBe('var x = 1;');
+  });
+
+  it('converts export let to var', () => {
+    const result = stripModuleSyntax('export let y = 2;');
+    expect(result.code.trim()).toBe('var y = 2;');
+  });
+
+  it('converts export var (keeps var)', () => {
+    const result = stripModuleSyntax('export var z = 3;');
+    expect(result.code.trim()).toBe('var z = 3;');
+  });
+
+  // -- export function → var assignment -----------------------------------
+
+  it('converts export function to var assignment', () => {
+    const result = stripModuleSyntax('export function greet(name) { return name; }');
+    expect(result.code.trim()).toBe('var greet = function greet(name) { return name; }');
+  });
+
+  it('converts export async function to var assignment', () => {
+    const result = stripModuleSyntax('export async function fetchData() {}');
+    expect(result.code.trim()).toBe('var fetchData = async function fetchData() {}');
+  });
+
+  // -- export class → var assignment --------------------------------------
+
+  it('converts export class to var assignment', () => {
+    const result = stripModuleSyntax('export class MyComponent {}');
+    expect(result.code.trim()).toBe('var MyComponent = class MyComponent {}');
+  });
+
+  // -- bare export block: export { a, b } ---------------------------------
+
+  it('converts bare exported function declarations to var', () => {
+    const input = 'function buildIndex() {}\nexport { buildIndex };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var buildIndex = function buildIndex()');
+    expect(result.code).not.toContain('export');
+    expect(result.bareExportNames).toEqual([{ local: 'buildIndex', exported: 'buildIndex' }]);
+  });
+
+  it('converts bare exported async function to var', () => {
+    const input = 'async function load() {}\nexport { load };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var load = async function load()');
+  });
+
+  it('converts bare exported const/let declarations to var', () => {
+    const input = 'const MAX = 10;\nlet count = 0;\nexport { MAX, count };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var MAX');
+    expect(result.code).toContain('var count');
+    expect(result.code).not.toContain('const MAX');
+    expect(result.code).not.toContain('let count');
+  });
+
+  it('handles multi-line bare export block', () => {
+    const input = 'function a() {}\nfunction b() {}\nexport {\n  a,\n  b\n};';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var a = function a()');
+    expect(result.code).toContain('var b = function b()');
+    expect(result.bareExportNames).toHaveLength(2);
+  });
+
+  // -- export { local as exported } aliasing ------------------------------
+
+  it('creates alias for export { local as exported }', () => {
+    const input = 'function foo() {}\nexport { foo as bar };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var foo = function foo()');
+    expect(result.code).toContain('var bar = foo;');
+    expect(result.bareExportNames).toEqual([{ local: 'foo', exported: 'bar' }]);
+  });
+
+  it('creates multiple aliases when needed', () => {
+    const input = 'function a() {}\nfunction b() {}\nexport { a as x, b as y };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var x = a;');
+    expect(result.code).toContain('var y = b;');
+  });
+
+  it('does not create alias when local equals exported', () => {
+    const input = 'function foo() {}\nexport { foo };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).not.toContain('var foo = foo;');
+  });
+
+  it('handles mix of aliased and non-aliased exports', () => {
+    const input = 'function a() {}\nfunction b() {}\nexport { a, b as c };';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var a = function a()');
+    expect(result.code).toContain('var b = function b()');
+    expect(result.code).not.toContain('var a = a;');
+    expect(result.code).toContain('var c = b;');
+  });
+
+  // -- Template literal preservation --------------------------------------
+
+  it('preserves export keyword inside template literal', () => {
+    const input = "const example = `export const x = 1;`;\nexport const y = 2;";
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('`export const x = 1;`');
+    expect(result.code).toContain('var y = 2;');
+  });
+
+  it('preserves export class inside template literal', () => {
+    const input = "const code = `export class Counter {}`;\nexport class Real {}";
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('`export class Counter {}`');
+    expect(result.code).toContain('var Real = class Real');
+  });
+
+  it('preserves nested template literal content', () => {
+    const input = "const x = `outer ${`inner export const a = 1;`} end`;\nexport const b = 2;";
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('inner export const a = 1;');
+    expect(result.code).toContain('var b = 2;');
+  });
+
+  it('handles deeply nested template literals', () => {
+    const input = "const x = `a ${y ? `b ${`c`}` : ''} d`;\nexport const z = 1;";
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('var z = 1;');
+    // Nested templates should be preserved without corruption
+    expect(result.code).toContain('`a ${');
+  });
+
+  // -- Edge cases ---------------------------------------------------------
+
+  it('returns empty bareExportNames when no bare exports', () => {
+    const result = stripModuleSyntax('export const x = 1;');
+    expect(result.bareExportNames).toEqual([]);
+  });
+
+  it('handles code with no imports or exports', () => {
+    const input = 'const x = 1;\nfunction foo() {}';
+    const result = stripModuleSyntax(input);
+    expect(result.code.trim()).toBe(input);
+    expect(result.bareExportNames).toEqual([]);
+  });
+
+  it('preserves indentation', () => {
+    const result = stripModuleSyntax('  export const x = 1;');
+    expect(result.code).toContain('  var x = 1;');
+  });
+
+  it('handles export inside string (not template)', () => {
+    const input = 'const s = "export const x = 1;";\nexport const y = 2;';
+    const result = stripModuleSyntax(input);
+    expect(result.code).toContain('"export const x = 1;"');
+    expect(result.code).toContain('var y = 2;');
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// CLI - minify ASI preservation
+// ---------------------------------------------------------------------------
+
+describe('CLI - minify ASI preservation', () => {
+  let minify;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const mod = await import('../cli/utils.js');
+    minify = mod.minify;
+  });
+
+  it('preserves newline between } and var', () => {
+    const input = 'var x = function() {}\nvar y = 1;';
+    const result = minify(input, '');
+    expect(result).toContain('}\nvar');
+    expect(result).not.toContain('}var');
+  });
+
+  it('preserves newline between } and identifier', () => {
+    const input = 'function a() {}\nfunction b() {}';
+    const result = minify(input, '');
+    expect(result).toContain('}\nfunction');
+    expect(result).not.toContain('}function');
+  });
+
+  it('preserves newline between } and const', () => {
+    const input = 'if (true) {}\nconst x = 1;';
+    const result = minify(input, '');
+    expect(result).toContain('}\nconst');
+  });
+
+  it('preserves newline between } and let', () => {
+    const input = 'if (true) {}\nlet x = 1;';
+    const result = minify(input, '');
+    expect(result).toContain('}\nlet');
+  });
+
+  it('does not add newline where none existed', () => {
+    const input = 'if(x){a()} else{b()}';
+    const result = minify(input, '');
+    // } followed by else on same line — no newline needed
+    expect(result).not.toContain('}\n');
+  });
+
+  it('handles }\\n followed by underscore-prefixed identifier', () => {
+    const input = 'var x = function() {}\n_init();';
+    const result = minify(input, '');
+    expect(result).toContain('}\n_init');
+  });
+
+  it('handles }\\n followed by $-prefixed identifier', () => {
+    const input = 'var x = function() {}\n$el.show();';
+    const result = minify(input, '');
+    expect(result).toContain('}\n$el');
+  });
+});
+
+
 // ---------------------------------------------------------------------------
 // CLI utils - stripComments
 // ---------------------------------------------------------------------------

package/tests/router.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { createRouter, getRouter } from '../src/router.js';
+import { createRouter, getRouter, matchRoute } from '../src/router.js';
 import { component } from '../src/component.js';
 
 // Register stub components used in route definitions so mount() doesn't throw
@@ -809,6 +809,70 @@ describe('Router - navigation chaining', () => {
 });
 
 
+// ---------------------------------------------------------------------------
+// matchRoute - standalone route matcher (DOM-free)
+// ---------------------------------------------------------------------------
+
+describe('matchRoute', () => {
+  const routes = [
+    { path: '/',            component: 'home-page'  },
+    { path: '/blog',        component: 'blog-list'  },
+    { path: '/blog/:slug',  component: 'blog-post'  },
+    { path: '/user/:id',    component: 'user-page'  },
+    { path: '/files/*',     component: 'file-browser' },
+  ];
+
+  it('matches a static route', () => {
+    expect(matchRoute(routes, '/')).toEqual({ component: 'home-page', params: {} });
+    expect(matchRoute(routes, '/blog')).toEqual({ component: 'blog-list', params: {} });
+  });
+
+  it('matches a parameterized route', () => {
+    expect(matchRoute(routes, '/blog/hello-world')).toEqual({
+      component: 'blog-post',
+      params: { slug: 'hello-world' },
+    });
+  });
+
+  it('matches multiple params', () => {
+    const r = [{ path: '/user/:id/post/:pid', component: 'user-post' }];
+    expect(matchRoute(r, '/user/42/post/7')).toEqual({
+      component: 'user-post',
+      params: { id: '42', pid: '7' },
+    });
+  });
+
+  it('matches wildcard routes', () => {
+    const result = matchRoute(routes, '/files/docs/readme.md');
+    expect(result.component).toBe('file-browser');
+  });
+
+  it('returns fallback when nothing matches', () => {
+    expect(matchRoute(routes, '/nope')).toEqual({ component: 'not-found', params: {} });
+  });
+
+  it('accepts a custom fallback component name', () => {
+    expect(matchRoute(routes, '/nope', '404-page')).toEqual({ component: '404-page', params: {} });
+  });
+
+  it('matches first route when multiple could match', () => {
+    const r = [
+      { path: '/a', component: 'first' },
+      { path: '/a', component: 'second' },
+    ];
+    expect(matchRoute(r, '/a').component).toBe('first');
+  });
+
+  it('handles per-route fallback aliases', () => {
+    const r = [
+      { path: '/docs/:section', component: 'docs-page', fallback: '/docs' },
+    ];
+    expect(matchRoute(r, '/docs/intro')).toEqual({ component: 'docs-page', params: { section: 'intro' } });
+    expect(matchRoute(r, '/docs')).toEqual({ component: 'docs-page', params: {} });
+  });
+});
+
+
 // ---------------------------------------------------------------------------
 // Hash mode path parsing
 // ---------------------------------------------------------------------------