zero-query 0.9.8 → 1.0.0

package/tests/utils.test.js

@@ -321,10 +321,10 @@ describe('isEqual', () => {
 });
 
 // ---------------------------------------------------------------------------
-// deepMerge — circular reference safety
+// deepMerge - circular reference safety
 // ---------------------------------------------------------------------------
 
-describe('deepMerge — circular reference safety', () => {
+describe('deepMerge - circular reference safety', () => {
   it('does not infinite-loop on circular source', () => {
     const a = { x: 1 };
     const b = { y: 2 };
@@ -541,14 +541,14 @@ describe('bus (event bus)', () => {
 describe('bus (EventBus)', () => {
   beforeEach(() => { bus.clear(); });
 
-  it('on/emit — fires handler for matching events', () => {
+  it('on/emit - fires handler for matching events', () => {
     const fn = vi.fn();
     bus.on('test', fn);
     bus.emit('test', 42);
     expect(fn).toHaveBeenCalledWith(42);
   });
 
-  it('off — removes handler', () => {
+  it('off - removes handler', () => {
     const fn = vi.fn();
     bus.on('test', fn);
     bus.off('test', fn);
@@ -564,7 +564,7 @@ describe('bus (EventBus)', () => {
     expect(fn).not.toHaveBeenCalled();
   });
 
-  it('once — fires handler only once', () => {
+  it('once - fires handler only once', () => {
     const fn = vi.fn();
     bus.once('test', fn);
     bus.emit('test', 'a');
@@ -573,7 +573,7 @@ describe('bus (EventBus)', () => {
     expect(fn).toHaveBeenCalledWith('a');
   });
 
-  it('clear — removes all handlers', () => {
+  it('clear - removes all handlers', () => {
     const fn = vi.fn();
     bus.on('a', fn);
     bus.on('b', fn);
@@ -590,10 +590,10 @@ describe('bus (EventBus)', () => {
 
 
 // ===========================================================================
-// throttle — window reset
+// throttle - window reset
 // ===========================================================================
 
-describe('throttle — edge cases', () => {
+describe('throttle - edge cases', () => {
   it('fires trailing call after wait period', async () => {
     vi.useFakeTimers();
     const fn = vi.fn();
@@ -612,10 +612,10 @@ describe('throttle — edge cases', () => {
 
 
 // ===========================================================================
-// deepClone — edge cases
+// deepClone - edge cases
 // ===========================================================================
 
-describe('deepClone — edge cases', () => {
+describe('deepClone - edge cases', () => {
   it('clones nested arrays', () => {
     const arr = [[1, 2], [3, 4]];
     const clone = deepClone(arr);
@@ -631,10 +631,10 @@ describe('deepClone — edge cases', () => {
 
 
 // ===========================================================================
-// deepMerge — multiple sources
+// deepMerge - multiple sources
 // ===========================================================================
 
-describe('deepMerge — edge cases', () => {
+describe('deepMerge - edge cases', () => {
   it('merges from multiple sources', () => {
     const result = deepMerge({}, { a: 1 }, { b: 2 }, { c: 3 });
     expect(result).toEqual({ a: 1, b: 2, c: 3 });
@@ -653,10 +653,10 @@ describe('deepMerge — edge cases', () => {
 
 
 // ===========================================================================
-// isEqual — deeply nested
+// isEqual - deeply nested
 // ===========================================================================
 
-describe('isEqual — edge cases', () => {
+describe('isEqual - edge cases', () => {
   it('deeply nested equal objects', () => {
     expect(isEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } })).toBe(true);
   });
@@ -686,10 +686,10 @@ describe('isEqual — edge cases', () => {
 
 
 // ===========================================================================
-// camelCase / kebabCase — edge cases
+// camelCase / kebabCase - edge cases
 // ===========================================================================
 
-describe('camelCase / kebabCase — edge cases', () => {
+describe('camelCase / kebabCase - edge cases', () => {
   it('camelCase single word', () => {
     expect(camelCase('hello')).toBe('hello');
   });
@@ -709,10 +709,10 @@ describe('camelCase / kebabCase — edge cases', () => {
 
 
 // ===========================================================================
-// html tag — escaping
+// html tag - escaping
 // ===========================================================================
 
-describe('html tag — edge cases', () => {
+describe('html tag - edge cases', () => {
   it('handles null interp value', () => {
     const result = html`<div>${null}</div>`;
     expect(result).toBe('<div></div>');
@@ -734,10 +734,10 @@ describe('html tag — edge cases', () => {
 
 
 // ===========================================================================
-// storage — error handling
+// storage - error handling
 // ===========================================================================
 
-describe('storage — parse error fallback', () => {
+describe('storage - parse error fallback', () => {
   it('returns fallback when JSON.parse fails', () => {
     localStorage.setItem('bad', '{invalid json');
     expect(storage.get('bad', 'default')).toBe('default');
@@ -747,7 +747,7 @@ describe('storage — parse error fallback', () => {
 
 
 // ===========================================================================
-// NEW UTILITIES — Array
+// NEW UTILITIES - Array
 // ===========================================================================
 
 describe('range', () => {
@@ -866,7 +866,7 @@ describe('groupBy', () => {
 
 
 // ===========================================================================
-// NEW UTILITIES — Object
+// NEW UTILITIES - Object
 // ===========================================================================
 
 describe('pick', () => {
@@ -1012,7 +1012,7 @@ describe('isEmpty', () => {
 
 
 // ===========================================================================
-// NEW UTILITIES — String
+// NEW UTILITIES - String
 // ===========================================================================
 
 describe('capitalize', () => {
@@ -1066,7 +1066,7 @@ describe('truncate', () => {
 
 
 // ===========================================================================
-// NEW UTILITIES — Number
+// NEW UTILITIES - Number
 // ===========================================================================
 
 describe('clamp', () => {
@@ -1099,7 +1099,7 @@ describe('clamp', () => {
 
 
 // ===========================================================================
-// NEW UTILITIES — Function
+// NEW UTILITIES - Function
 // ===========================================================================
 
 describe('memoize', () => {
@@ -1154,7 +1154,7 @@ describe('memoize', () => {
 
 
 // ===========================================================================
-// NEW UTILITIES — Async
+// NEW UTILITIES - Async
 // ===========================================================================
 
 describe('retry', () => {
@@ -1238,3 +1238,140 @@ describe('timeout', () => {
     clearSpy.mockRestore();
   });
 });
+
+
+// ===========================================================================
+// memoize - LRU behaviour
+// ===========================================================================
+
+describe('memoize - LRU eviction', () => {
+  it('promotes recently-read entries so they survive eviction', () => {
+    const fn = vi.fn(x => x * 2);
+    const mem = memoize(fn, { maxSize: 3 });
+
+    mem(1); // cache: [1]
+    mem(2); // cache: [1, 2]
+    mem(3); // cache: [1, 2, 3]
+
+    // Access 1 to promote it (LRU moves it to newest)
+    mem(1); // cache: [2, 3, 1]
+    expect(fn).toHaveBeenCalledTimes(3); // still cached, no recompute
+
+    // Insert 4 -> should evict 2 (least recently used), NOT 1
+    mem(4); // cache: [3, 1, 4]
+    expect(fn).toHaveBeenCalledTimes(4);
+
+    // 1 should still be cached (was promoted)
+    mem(1);
+    expect(fn).toHaveBeenCalledTimes(4); // no recompute
+
+    // 2 should be evicted
+    mem(2);
+    expect(fn).toHaveBeenCalledTimes(5); // recomputation
+  });
+
+  it('evicts in LRU order, not insertion order', () => {
+    const fn = vi.fn(x => x);
+    const mem = memoize(fn, { maxSize: 2 });
+
+    mem('a'); // [a]
+    mem('b'); // [a, b]
+
+    // Read 'a' - makes 'b' the LRU
+    mem('a'); // [b, a]
+
+    // Insert 'c' - should evict 'b', not 'a'
+    mem('c'); // [a, c]
+
+    // 'a' still cached
+    mem('a');
+    expect(fn).toHaveBeenCalledTimes(3); // a, b, c
+
+    // 'b' was evicted
+    mem('b');
+    expect(fn).toHaveBeenCalledTimes(4);
+  });
+});
+
+
+// ===========================================================================
+// deepClone - enhanced types
+// ===========================================================================
+
+describe('deepClone - enhanced types', () => {
+  it('clones Date objects', () => {
+    const date = new Date('2024-01-15T12:00:00Z');
+    const clone = deepClone(date);
+    expect(clone).toEqual(date);
+    expect(clone).not.toBe(date);
+    expect(clone instanceof Date).toBe(true);
+    expect(clone.getTime()).toBe(date.getTime());
+  });
+
+  it('clones nested Dates', () => {
+    const obj = { created: new Date('2024-01-15T12:00:00Z'), meta: { updated: new Date('2024-06-15T12:00:00Z') } };
+    const clone = deepClone(obj);
+    clone.created.setFullYear(2000);
+    expect(obj.created.getFullYear()).toBe(2024);
+  });
+
+  it('clones RegExp', () => {
+    const re = /hello/gi;
+    const clone = deepClone(re);
+    expect(clone).toEqual(re);
+    expect(clone).not.toBe(re);
+    expect(clone.source).toBe('hello');
+    expect(clone.flags).toBe('gi');
+  });
+
+  it('clones Map', () => {
+    const map = new Map([['a', 1], ['b', { deep: true }]]);
+    const clone = deepClone(map);
+    expect(clone).not.toBe(map);
+    expect(clone.get('a')).toBe(1);
+    clone.get('b').deep = false;
+    expect(map.get('b').deep).toBe(true);
+  });
+
+  it('clones Set', () => {
+    const set = new Set([1, 2, { x: 3 }]);
+    const clone = deepClone(set);
+    expect(clone).not.toBe(set);
+    expect(clone.size).toBe(3);
+    expect(clone.has(1)).toBe(true);
+    expect(clone.has(2)).toBe(true);
+  });
+
+  it('handles undefined values in objects', () => {
+    const obj = { a: 1, b: undefined, c: 'hello' };
+    const clone = deepClone(obj);
+    expect(clone.b).toBeUndefined();
+    expect('b' in clone).toBe(true);
+  });
+
+  it('handles null values', () => {
+    const obj = { a: null, b: { c: null } };
+    const clone = deepClone(obj);
+    expect(clone.a).toBeNull();
+    expect(clone.b.c).toBeNull();
+  });
+
+  it('handles circular references', () => {
+    const obj = { a: 1 };
+    obj.self = obj;
+    const clone = deepClone(obj);
+    expect(clone.a).toBe(1);
+    expect(clone.self).toBe(clone);
+    expect(clone.self).not.toBe(obj);
+  });
+
+  it('handles nested circular references', () => {
+    const a = { name: 'a' };
+    const b = { name: 'b', ref: a };
+    a.ref = b;
+    const clone = deepClone(a);
+    expect(clone.name).toBe('a');
+    expect(clone.ref.name).toBe('b');
+    expect(clone.ref.ref).toBe(clone);
+  });
+});

package/types/collection.d.ts

@@ -1,5 +1,5 @@
 /**
- * ZQueryCollection — chainable DOM element wrapper.
+ * ZQueryCollection - chainable DOM element wrapper.
  *
  * Returned by `$()`, `$.all()`, `$.create()`, and many traversal methods.
  * Similar to a jQuery object: wraps an array of elements with fluent methods.
@@ -50,7 +50,7 @@ export class ZQueryCollection {
   /** Convert to a plain `Element[]`. */
   toArray(): Element[];
 
-  /** Iterable protocol — works with `for...of` and spread. */
+  /** Iterable protocol - works with `for...of` and spread. */
   [Symbol.iterator](): IterableIterator<Element>;
 
   // -- Traversal -----------------------------------------------------------

package/types/component.d.ts

@@ -1,5 +1,5 @@
 /**
- * Component system — define, mount, and manage reactive components.
+ * Component system - define, mount, and manage reactive components.
  *
  * @module component
  */
@@ -21,7 +21,7 @@ export interface ComponentDefinition {
    */
   render?(this: ComponentInstance): string;
 
-  /** CSS string — scoped to the component root on first render. */
+  /** CSS string - scoped to the component root on first render. */
   styles?: string;
 
   /**
@@ -55,7 +55,7 @@ export interface ComponentDefinition {
   destroyed?(this: ComponentInstance): void;
 
   /**
-   * Computed properties — lazy getters derived from state.
+   * Computed properties - lazy getters derived from state.
    * Each function receives the raw state as its argument.
    * Access via `this.computed.name` in methods and templates.
    */
@@ -100,7 +100,7 @@ export interface ComponentInstance {
   templates: Record<string, string>;
 
   /**
-   * Computed properties — lazy getters derived from state.
+   * Computed properties - lazy getters derived from state.
    * Defined via `computed` in the component definition.
    */
   readonly computed: Record<string, any>;
@@ -116,7 +116,7 @@ export interface ComponentInstance {
 
   /**
    * Manually queue a re-render (microtask-batched).
-   * Safe to call from anywhere — state mutations during render are coalesced.
+   * Safe to call from anywhere - state mutations during render are coalesced.
    */
   _scheduleUpdate(): void;
 

package/types/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * Structured error handling — error codes, error class, and global handler.
+ * Structured error handling - error codes, error class, and global handler.
  *
  * @module errors
  */
@@ -41,6 +41,12 @@ export declare const ErrorCode: {
   readonly HTTP_INTERCEPTOR: 'ZQ_HTTP_INTERCEPTOR';
   readonly HTTP_PARSE: 'ZQ_HTTP_PARSE';
 
+  // SSR
+  readonly SSR_RENDER: 'ZQ_SSR_RENDER';
+  readonly SSR_COMPONENT: 'ZQ_SSR_COMPONENT';
+  readonly SSR_HYDRATION: 'ZQ_SSR_HYDRATION';
+  readonly SSR_PAGE: 'ZQ_SSR_PAGE';
+
   // General
   readonly INVALID_ARGUMENT: 'ZQ_INVALID_ARGUMENT';
 };
@@ -71,13 +77,14 @@ export type ZQueryErrorHandler = (error: ZQueryError) => void;
 
 /**
  * Register a global error handler. Called whenever zQuery catches an
- * error internally. Pass `null` to remove.
+ * error internally. Multiple handlers are supported. Pass `null` to clear all.
+ * @returns Unsubscribe function to remove this handler.
  */
-export function onError(handler: ZQueryErrorHandler | null): void;
+export function onError(handler: ZQueryErrorHandler | null): () => void;
 
 /**
  * Report an error through the global handler and console.
- * Non-throwing — used for recoverable errors in callbacks, lifecycle hooks, etc.
+ * Non-throwing - used for recoverable errors in callbacks, lifecycle hooks, etc.
  */
 export function reportError(
   code: ErrorCodeValue,
@@ -101,3 +108,28 @@ export function guardCallback<T extends (...args: any[]) => any>(
  * Throws `ZQueryError` with `INVALID_ARGUMENT` on failure.
  */
 export function validate(value: any, name: string, expectedType?: string): void;
+
+/** Formatted error structure for overlays and logging. */
+export interface FormattedError {
+  code: string;
+  type: string;
+  message: string;
+  context: Record<string, any>;
+  stack: string;
+  cause: FormattedError | null;
+}
+
+/**
+ * Format a ZQueryError into a structured object suitable for overlays/logging.
+ */
+export function formatError(err: ZQueryError | Error): FormattedError;
+
+/**
+ * Async version of guardCallback - wraps an async function so that
+ * rejections are caught, reported, and don't crash execution.
+ */
+export function guardAsync<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  code: ErrorCodeValue,
+  context?: Record<string, any>,
+): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | undefined>;

package/types/http.d.ts

@@ -1,5 +1,5 @@
 /**
- * HTTP Client — fetch-based wrapper with interceptors and auto-JSON.
+ * HTTP Client - fetch-based wrapper with interceptors and auto-JSON.
  *
  * @module http
  */
@@ -61,7 +61,7 @@ export interface HttpClient {
   patch<T = any>(url: string, data?: any, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
   /** DELETE request. */
   delete<T = any>(url: string, data?: any, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
-  /** HEAD request — no body, useful for checking resource existence or headers. */
+  /** HEAD request - no body, useful for checking resource existence or headers. */
   head<T = any>(url: string, opts?: HttpRequestOptions): Promise<HttpResponse<T>>;
 
   /** Update default configuration for all subsequent requests. */
@@ -85,7 +85,7 @@ export interface HttpClient {
   /** Create a new `AbortController` for manual request cancellation. */
   createAbort(): AbortController;
 
-  /** Direct passthrough to native `fetch()` — no JSON handling, no interceptors. */
+  /** Direct passthrough to native `fetch()` - no JSON handling, no interceptors. */
   raw(url: string, opts?: RequestInit): Promise<Response>;
 }
 

package/types/misc.d.ts

@@ -10,7 +10,7 @@
 
 /**
  * Morph an existing DOM element's children to match new HTML.
- * Only touches nodes that actually differ — preserves focus, scroll
+ * Only touches nodes that actually differ - preserves focus, scroll
  * positions, video playback, and other live DOM state.
  *
  * Use `z-key="uniqueId"` attributes on list items for keyed reconciliation.
@@ -22,7 +22,7 @@
 export function morph(rootEl: Element, newHTML: string): void;
 
 /**
- * Morph a single element in place — diffs attributes and children
+ * Morph a single element in place - diffs attributes and children
  * without replacing the node reference. If the tag name matches, the
  * element is patched in place (preserving identity). If the tag differs,
  * the element is replaced.
@@ -58,11 +58,11 @@ export function safeEval(expr: string, scope: object[]): any;
 //
 // ─── Structural Directives ──────────────────────────────────────────────
 //
-//   z-if="expression"          Conditional rendering — element removed when falsy.
+//   z-if="expression"          Conditional rendering - element removed when falsy.
 //   z-else-if="expression"     Else-if branch (must be immediate sibling of z-if).
 //   z-else                     Default branch (must follow z-if or z-else-if).
 //
-//   z-for="item in items"      List rendering — repeats the element per item.
+//   z-for="item in items"      List rendering - repeats the element per item.
 //     {{item.prop}}              Use double-brace interpolation for item data.
 //     (item, index) in items     Destructured index support.
 //     n in 5                     Number range → [1, 2, 3, 4, 5].
@@ -100,9 +100,9 @@ export function safeEval(expr: string, scope: object[]): any;
 //     Supports: input, textarea, select, select[multiple], contenteditable.
 //     Nested keys: z-model="user.name" → this.state.user.name.
 //     Modifiers (boolean attributes on same element):
-//       z-lazy    — update on 'change' instead of 'input' (update on blur).
-//       z-trim    — auto .trim() whitespace before writing to state.
-//       z-number  — force Number() conversion regardless of input type.
+//       z-lazy    - update on 'change' instead of 'input' (update on blur).
+//       z-trim    - auto .trim() whitespace before writing to state.
+//       z-number  - force Number() conversion regardless of input type.
 //
 //   z-ref="name"               Element reference → this.refs.name.
 //
@@ -134,9 +134,9 @@ export function safeEval(expr: string, scope: object[]): any;
 //
 // ─── Slot System ────────────────────────────────────────────────────────
 //
-//   <slot>                     Default slot — replaced with child content
+//   <slot>                     Default slot - replaced with child content
 //                              passed by the parent component.
-//   <slot name="header">       Named slot — replaced with child content that
+//   <slot name="header">       Named slot - replaced with child content that
 //                              has a matching slot="header" attribute.
 //   <slot>fallback</slot>      Fallback content shown when no slot content provided.
 //

package/types/reactive.d.ts

@@ -1,12 +1,12 @@
 /**
- * Reactive primitives — deep proxies and signals.
+ * Reactive primitives - deep proxies and signals.
  *
  * @module reactive
  */
 
 /** Marker properties added to every reactive proxy. */
 export interface ReactiveProxy<T extends object = object> {
-  /** Always `true` — indicates this object is wrapped in a reactive Proxy. */
+  /** Always `true` - indicates this object is wrapped in a reactive Proxy. */
   readonly __isReactive: true;
   /** The original un-proxied object. */
   readonly __raw: T;
@@ -65,7 +65,7 @@ export function computed<T>(fn: () => T): Signal<T>;
  * Re-runs automatically when any tracked signal changes.
  *
  * @param fn The effect function. Executed immediately on creation, then on signal changes.
- * @returns A dispose function — calling it stops tracking and prevents re-runs.
+ * @returns A dispose function - calling it stops tracking and prevents re-runs.
  *
  * @example
  * const count = signal(0);
@@ -74,3 +74,25 @@ export function computed<T>(fn: () => T): Signal<T>;
  * stop();          // effect no longer runs
  */
 export function effect(fn: () => void): () => void;
+
+/**
+ * Batch multiple signal writes - subscribers and effects fire once at the end.
+ * Nested batches are merged into the outermost one.
+ *
+ * @example
+ * const a = signal(0);
+ * const b = signal(0);
+ * batch(() => {
+ *   a.value = 1;
+ *   b.value = 2;
+ * }); // effects run once with both values updated
+ */
+export function batch(fn: () => void): void;
+
+/**
+ * Execute a function without tracking signal reads as dependencies.
+ * Useful inside effects when you need to read a signal without subscribing.
+ *
+ * @returns The return value of `fn`.
+ */
+export function untracked<T>(fn: () => T): T;

package/types/router.d.ts

@@ -1,5 +1,5 @@
 /**
- * SPA Router — history and hash-based client-side routing.
+ * SPA Router - history and hash-based client-side routing.
  *
  * @module router
  */
@@ -39,7 +39,11 @@ export interface NavigationContext {
 
 /** Router configuration. */
 export interface RouterConfig {
-  /** Outlet element where route components are rendered. */
+  /**
+   * Outlet element where route components are rendered.
+   * If omitted, the router auto-detects a `<z-outlet>` element in the DOM.
+   * Acts as an explicit override of the default `<z-outlet>` lookup.
+   */
   el?: string | Element;
   /** Routing mode (default: `'history'`; `'hash'` for file:// or hash routing). */
   mode?: 'history' | 'hash';
@@ -86,7 +90,7 @@ export interface RouterInstance {
   remove(path: string): RouterInstance;
 
   /**
-   * Navigation guard — runs before each route change.
+   * Navigation guard - runs before each route change.
    * Return `false` to cancel, or a `string` to redirect.
    */
   beforeEach(
@@ -111,10 +115,10 @@ export interface RouterInstance {
 
   /**
    * Push a lightweight history entry for in-component UI state (modal, tab, panel).
-   * The URL does NOT change — only a history entry is added so the back button
+   * The URL does NOT change - only a history entry is added so the back button
    * can undo the UI change before navigating away from the route.
-   * @param key — identifier for the substate (e.g. 'modal', 'tab')
-   * @param data — arbitrary serializable state
+   * @param key - identifier for the substate (e.g. 'modal', 'tab')
+   * @param data - arbitrary serializable state
    * @example
    * router.pushSubstate('modal', { id: 'confirm-delete' });
    */