zero-query 1.0.9 → 1.2.0

package/types/component.d.ts

@@ -1,186 +1,186 @@
-/**
- * Component system - define, mount, and manage reactive components.
- *
- * @module component
- */
-
-import type { ReactiveProxy } from './reactive';
-import type { NavigationContext } from './router';
-
-/** The object passed to `$.component()` to define a component. */
-export interface ComponentDefinition {
-  /**
-   * Initial reactive state.
-   * A function form is recommended so each instance gets its own copy.
-   */
-  state?: Record<string, any> | (() => Record<string, any>);
-
-  /**
-   * Returns an HTML string. Called on every state change.
-   * `this` is the component instance.
-   */
-  render?(this: ComponentInstance): string;
-
-  /** CSS string - scoped to the component root on first render. */
-  styles?: string;
-
-  /**
-   * URL (or array / object map of URLs) to external HTML template file(s).
-   * If `render()` is also defined, `render()` takes priority.
-   */
-  templateUrl?: string | string[] | Record<string, string>;
-
-  /**
-   * URL (or array of URLs) to external CSS file(s).
-   * Fetched and auto-scoped on first mount; merged with `styles` if both present.
-   */
-  styleUrl?: string | string[];
-
-  /**
-   * Override the base path for resolving relative `templateUrl` and `styleUrl`
-   * paths. Normally auto-detected from the calling file.
-   */
-  base?: string;
-
-  /** Called before first render (during construction). */
-  init?(this: ComponentInstance): void;
-
-  /** Called once after first render and DOM insertion. */
-  mounted?(this: ComponentInstance): void;
-
-  /** Called after every subsequent re-render. */
-  updated?(this: ComponentInstance): void;
-
-  /** Called when the component is destroyed. Clean up subscriptions here. */
-  destroyed?(this: ComponentInstance): void;
-
-  /**
-   * 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.
-   */
-  computed?: Record<string, (state: Record<string, any>) => any>;
-
-  /**
-   * Watch state keys for changes.
-   * Keys support dot-path notation (e.g. `'user.name'`).
-   * Handler receives `(newValue, oldValue)`.
-   */
-  watch?: Record<
-    string,
-    | ((this: ComponentInstance, newVal: any, oldVal: any) => void)
-    | { handler: (this: ComponentInstance, newVal: any, oldVal: any) => void }
-  >;
-
-  /** Additional keys become instance methods (bound to the instance). */
-  [method: string]: any;
-}
-
-/** The runtime instance of a mounted component. */
-export interface ComponentInstance {
-  /** Reactive state proxy. Mutating triggers re-render. */
-  state: Record<string, any> & ReactiveProxy;
-
-  /**
-   * Frozen props passed from parent / router.
-   * When mounted by the router, includes `$route`, `$query`, and `$params`.
-   */
-  readonly props: Readonly<
-    Record<string, any> & {
-      $route?: NavigationContext;
-      $query?: Record<string, string>;
-      $params?: Record<string, string>;
-    }
-  >;
-
-  /** Map of `z-ref` name → DOM element. Populated after each render. */
-  refs: Record<string, Element>;
-
-  /** Keyed template map (when using multi-`templateUrl`). */
-  templates: Record<string, string>;
-
-  /**
-   * Computed properties - lazy getters derived from state.
-   * Defined via `computed` in the component definition.
-   */
-  readonly computed: Record<string, any>;
-
-  /** Merge partial state (triggers re-render). */
-  setState(partial: Record<string, any>): void;
-
-  /** Dispatch a bubbling `CustomEvent` from the component root. */
-  emit(name: string, detail?: any): void;
-
-  /** Teardown: removes listeners, scoped styles, clears DOM. */
-  destroy(): void;
-
-  /**
-   * Manually queue a re-render (microtask-batched).
-   * Safe to call from anywhere - state mutations during render are coalesced.
-   */
-  _scheduleUpdate(): void;
-
-  /** Any user-defined methods from the component definition. */
-  [method: string]: any;
-}
-
-/**
- * Register a new component.
- * @param name Must contain a hyphen (Web Component convention).
- * @param definition Component definition object.
- */
-export function component(name: string, definition: ComponentDefinition): void;
-
-/**
- * Mount a registered component into a target element.
- * @returns The component instance.
- */
-export function mount(
-  target: string | Element,
-  componentName: string,
-  props?: Record<string, any>,
-): ComponentInstance;
-
-/**
- * Scan `root` for elements whose tag matches a registered component and mount them.
- * @param root Defaults to `document.body`.
- */
-export function mountAll(root?: Element): void;
-
-/** Get the component instance mounted on `target`. */
-export function getInstance(target: string | Element): ComponentInstance | null;
-
-/** Destroy the component at the given target. */
-export function destroy(target: string | Element): void;
-
-/** Returns an object of all registered component definitions (for debugging). */
-export function getRegistry(): Record<string, ComponentDefinition>;
-
-/**
- * Pre-load external templates and styles for a registered component.
- * Useful for warming the cache before navigation to avoid blank flashes.
- * @param name Registered component name.
- */
-export function prefetch(name: string): Promise<void>;
-
-/** Handle returned by `$.style()`. */
-export interface StyleHandle {
-  /** Remove all injected `<link>` elements. */
-  remove(): void;
-  /** Resolves when all stylesheets have loaded. */
-  ready: Promise<void>;
-}
-
-/** Options for `$.style()`. */
-export interface StyleOptions {
-  /** Hide page until loaded to prevent FOUC (default `true`). */
-  critical?: boolean;
-  /** Background color while hidden during critical load (default `'#0d1117'`). */
-  bg?: string;
-}
-
-/**
- * Dynamically load global (unscoped) stylesheet file(s) into `<head>`.
- * Relative paths resolve relative to the calling file.
- */
-export function style(urls: string | string[], opts?: StyleOptions): StyleHandle;
+/**
+ * Component system - define, mount, and manage reactive components.
+ *
+ * @module component
+ */
+
+import type { ReactiveProxy } from './reactive';
+import type { NavigationContext } from './router';
+
+/** The object passed to `$.component()` to define a component. */
+export interface ComponentDefinition {
+  /**
+   * Initial reactive state.
+   * A function form is recommended so each instance gets its own copy.
+   */
+  state?: Record<string, any> | (() => Record<string, any>);
+
+  /**
+   * Returns an HTML string. Called on every state change.
+   * `this` is the component instance.
+   */
+  render?(this: ComponentInstance): string;
+
+  /** CSS string - scoped to the component root on first render. */
+  styles?: string;
+
+  /**
+   * URL (or array / object map of URLs) to external HTML template file(s).
+   * If `render()` is also defined, `render()` takes priority.
+   */
+  templateUrl?: string | string[] | Record<string, string>;
+
+  /**
+   * URL (or array of URLs) to external CSS file(s).
+   * Fetched and auto-scoped on first mount; merged with `styles` if both present.
+   */
+  styleUrl?: string | string[];
+
+  /**
+   * Override the base path for resolving relative `templateUrl` and `styleUrl`
+   * paths. Normally auto-detected from the calling file.
+   */
+  base?: string;
+
+  /** Called before first render (during construction). */
+  init?(this: ComponentInstance): void;
+
+  /** Called once after first render and DOM insertion. */
+  mounted?(this: ComponentInstance): void;
+
+  /** Called after every subsequent re-render. */
+  updated?(this: ComponentInstance): void;
+
+  /** Called when the component is destroyed. Clean up subscriptions here. */
+  destroyed?(this: ComponentInstance): void;
+
+  /**
+   * 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.
+   */
+  computed?: Record<string, (state: Record<string, any>) => any>;
+
+  /**
+   * Watch state keys for changes.
+   * Keys support dot-path notation (e.g. `'user.name'`).
+   * Handler receives `(newValue, oldValue)`.
+   */
+  watch?: Record<
+    string,
+    | ((this: ComponentInstance, newVal: any, oldVal: any) => void)
+    | { handler: (this: ComponentInstance, newVal: any, oldVal: any) => void }
+  >;
+
+  /** Additional keys become instance methods (bound to the instance). */
+  [method: string]: any;
+}
+
+/** The runtime instance of a mounted component. */
+export interface ComponentInstance {
+  /** Reactive state proxy. Mutating triggers re-render. */
+  state: Record<string, any> & ReactiveProxy;
+
+  /**
+   * Frozen props passed from parent / router.
+   * When mounted by the router, includes `$route`, `$query`, and `$params`.
+   */
+  readonly props: Readonly<
+    Record<string, any> & {
+      $route?: NavigationContext;
+      $query?: Record<string, string>;
+      $params?: Record<string, string>;
+    }
+  >;
+
+  /** Map of `z-ref` name → DOM element. Populated after each render. */
+  refs: Record<string, Element>;
+
+  /** Keyed template map (when using multi-`templateUrl`). */
+  templates: Record<string, string>;
+
+  /**
+   * Computed properties - lazy getters derived from state.
+   * Defined via `computed` in the component definition.
+   */
+  readonly computed: Record<string, any>;
+
+  /** Merge partial state (triggers re-render). */
+  setState(partial: Record<string, any>): void;
+
+  /** Dispatch a bubbling `CustomEvent` from the component root. */
+  emit(name: string, detail?: any): void;
+
+  /** Teardown: removes listeners, scoped styles, clears DOM. */
+  destroy(): void;
+
+  /**
+   * Manually queue a re-render (microtask-batched).
+   * Safe to call from anywhere - state mutations during render are coalesced.
+   */
+  _scheduleUpdate(): void;
+
+  /** Any user-defined methods from the component definition. */
+  [method: string]: any;
+}
+
+/**
+ * Register a new component.
+ * @param name Must contain a hyphen (Web Component convention).
+ * @param definition Component definition object.
+ */
+export function component(name: string, definition: ComponentDefinition): void;
+
+/**
+ * Mount a registered component into a target element.
+ * @returns The component instance.
+ */
+export function mount(
+  target: string | Element,
+  componentName: string,
+  props?: Record<string, any>,
+): ComponentInstance;
+
+/**
+ * Scan `root` for elements whose tag matches a registered component and mount them.
+ * @param root Defaults to `document.body`.
+ */
+export function mountAll(root?: Element): void;
+
+/** Get the component instance mounted on `target`. */
+export function getInstance(target: string | Element): ComponentInstance | null;
+
+/** Destroy the component at the given target. */
+export function destroy(target: string | Element): void;
+
+/** Returns an object of all registered component definitions (for debugging). */
+export function getRegistry(): Record<string, ComponentDefinition>;
+
+/**
+ * Pre-load external templates and styles for a registered component.
+ * Useful for warming the cache before navigation to avoid blank flashes.
+ * @param name Registered component name.
+ */
+export function prefetch(name: string): Promise<void>;
+
+/** Handle returned by `$.style()`. */
+export interface StyleHandle {
+  /** Remove all injected `<link>` elements. */
+  remove(): void;
+  /** Resolves when all stylesheets have loaded. */
+  ready: Promise<void>;
+}
+
+/** Options for `$.style()`. */
+export interface StyleOptions {
+  /** Hide page until loaded to prevent FOUC (default `true`). */
+  critical?: boolean;
+  /** Background color while hidden during critical load (default `'#0d1117'`). */
+  bg?: string;
+}
+
+/**
+ * Dynamically load global (unscoped) stylesheet file(s) into `<head>`.
+ * Relative paths resolve relative to the calling file.
+ */
+export function style(urls: string | string[], opts?: StyleOptions): StyleHandle;

package/types/errors.d.ts

@@ -1,135 +1,135 @@
-/**
- * Structured error handling - error codes, error class, and global handler.
- *
- * @module errors
- */
-
-/** All structured error codes used by zQuery. */
-export declare const ErrorCode: {
-  // Reactive
-  readonly REACTIVE_CALLBACK: 'ZQ_REACTIVE_CALLBACK';
-  readonly SIGNAL_CALLBACK: 'ZQ_SIGNAL_CALLBACK';
-  readonly EFFECT_EXEC: 'ZQ_EFFECT_EXEC';
-
-  // Expression parser
-  readonly EXPR_PARSE: 'ZQ_EXPR_PARSE';
-  readonly EXPR_EVAL: 'ZQ_EXPR_EVAL';
-  readonly EXPR_UNSAFE_ACCESS: 'ZQ_EXPR_UNSAFE_ACCESS';
-
-  // Component
-  readonly COMP_INVALID_NAME: 'ZQ_COMP_INVALID_NAME';
-  readonly COMP_NOT_FOUND: 'ZQ_COMP_NOT_FOUND';
-  readonly COMP_MOUNT_TARGET: 'ZQ_COMP_MOUNT_TARGET';
-  readonly COMP_RENDER: 'ZQ_COMP_RENDER';
-  readonly COMP_LIFECYCLE: 'ZQ_COMP_LIFECYCLE';
-  readonly COMP_RESOURCE: 'ZQ_COMP_RESOURCE';
-  readonly COMP_DIRECTIVE: 'ZQ_COMP_DIRECTIVE';
-
-  // Router
-  readonly ROUTER_LOAD: 'ZQ_ROUTER_LOAD';
-  readonly ROUTER_GUARD: 'ZQ_ROUTER_GUARD';
-  readonly ROUTER_RESOLVE: 'ZQ_ROUTER_RESOLVE';
-
-  // Store
-  readonly STORE_ACTION: 'ZQ_STORE_ACTION';
-  readonly STORE_MIDDLEWARE: 'ZQ_STORE_MIDDLEWARE';
-  readonly STORE_SUBSCRIBE: 'ZQ_STORE_SUBSCRIBE';
-
-  // HTTP
-  readonly HTTP_REQUEST: 'ZQ_HTTP_REQUEST';
-  readonly HTTP_TIMEOUT: 'ZQ_HTTP_TIMEOUT';
-  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';
-};
-
-/** Union of all error code string values. */
-export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
-
-/** Structured error class used throughout zQuery. */
-export class ZQueryError extends Error {
-  readonly name: 'ZQueryError';
-  /** Machine-readable error code (e.g. `'ZQ_COMP_RENDER'`). */
-  readonly code: ErrorCodeValue;
-  /** Extra contextual data (component name, expression string, etc.). */
-  readonly context: Record<string, any>;
-  /** Original error that caused this one, if any. */
-  readonly cause?: Error;
-
-  constructor(
-    code: ErrorCodeValue,
-    message: string,
-    context?: Record<string, any>,
-    cause?: Error,
-  );
-}
-
-/** Error handler callback type. */
-export type ZQueryErrorHandler = (error: ZQueryError) => void;
-
-/**
- * Register a global error handler. Called whenever zQuery catches an
- * 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;
-
-/**
- * Report an error through the global handler and console.
- * Non-throwing - used for recoverable errors in callbacks, lifecycle hooks, etc.
- */
-export function reportError(
-  code: ErrorCodeValue,
-  message: string,
-  context?: Record<string, any>,
-  cause?: Error,
-): void;
-
-/**
- * Wrap a callback so that thrown errors are caught, reported via `reportError`,
- * and don't crash the current execution context.
- */
-export function guardCallback<T extends (...args: any[]) => any>(
-  fn: T,
-  code: ErrorCodeValue,
-  context?: Record<string, any>,
-): (...args: Parameters<T>) => ReturnType<T> | undefined;
-
-/**
- * Validate a required value is defined and of the expected type.
- * 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>;
+/**
+ * Structured error handling - error codes, error class, and global handler.
+ *
+ * @module errors
+ */
+
+/** All structured error codes used by zQuery. */
+export declare const ErrorCode: {
+  // Reactive
+  readonly REACTIVE_CALLBACK: 'ZQ_REACTIVE_CALLBACK';
+  readonly SIGNAL_CALLBACK: 'ZQ_SIGNAL_CALLBACK';
+  readonly EFFECT_EXEC: 'ZQ_EFFECT_EXEC';
+
+  // Expression parser
+  readonly EXPR_PARSE: 'ZQ_EXPR_PARSE';
+  readonly EXPR_EVAL: 'ZQ_EXPR_EVAL';
+  readonly EXPR_UNSAFE_ACCESS: 'ZQ_EXPR_UNSAFE_ACCESS';
+
+  // Component
+  readonly COMP_INVALID_NAME: 'ZQ_COMP_INVALID_NAME';
+  readonly COMP_NOT_FOUND: 'ZQ_COMP_NOT_FOUND';
+  readonly COMP_MOUNT_TARGET: 'ZQ_COMP_MOUNT_TARGET';
+  readonly COMP_RENDER: 'ZQ_COMP_RENDER';
+  readonly COMP_LIFECYCLE: 'ZQ_COMP_LIFECYCLE';
+  readonly COMP_RESOURCE: 'ZQ_COMP_RESOURCE';
+  readonly COMP_DIRECTIVE: 'ZQ_COMP_DIRECTIVE';
+
+  // Router
+  readonly ROUTER_LOAD: 'ZQ_ROUTER_LOAD';
+  readonly ROUTER_GUARD: 'ZQ_ROUTER_GUARD';
+  readonly ROUTER_RESOLVE: 'ZQ_ROUTER_RESOLVE';
+
+  // Store
+  readonly STORE_ACTION: 'ZQ_STORE_ACTION';
+  readonly STORE_MIDDLEWARE: 'ZQ_STORE_MIDDLEWARE';
+  readonly STORE_SUBSCRIBE: 'ZQ_STORE_SUBSCRIBE';
+
+  // HTTP
+  readonly HTTP_REQUEST: 'ZQ_HTTP_REQUEST';
+  readonly HTTP_TIMEOUT: 'ZQ_HTTP_TIMEOUT';
+  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';
+};
+
+/** Union of all error code string values. */
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+/** Structured error class used throughout zQuery. */
+export class ZQueryError extends Error {
+  readonly name: 'ZQueryError';
+  /** Machine-readable error code (e.g. `'ZQ_COMP_RENDER'`). */
+  readonly code: ErrorCodeValue;
+  /** Extra contextual data (component name, expression string, etc.). */
+  readonly context: Record<string, any>;
+  /** Original error that caused this one, if any. */
+  readonly cause?: Error;
+
+  constructor(
+    code: ErrorCodeValue,
+    message: string,
+    context?: Record<string, any>,
+    cause?: Error,
+  );
+}
+
+/** Error handler callback type. */
+export type ZQueryErrorHandler = (error: ZQueryError) => void;
+
+/**
+ * Register a global error handler. Called whenever zQuery catches an
+ * 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;
+
+/**
+ * Report an error through the global handler and console.
+ * Non-throwing - used for recoverable errors in callbacks, lifecycle hooks, etc.
+ */
+export function reportError(
+  code: ErrorCodeValue,
+  message: string,
+  context?: Record<string, any>,
+  cause?: Error,
+): void;
+
+/**
+ * Wrap a callback so that thrown errors are caught, reported via `reportError`,
+ * and don't crash the current execution context.
+ */
+export function guardCallback<T extends (...args: any[]) => any>(
+  fn: T,
+  code: ErrorCodeValue,
+  context?: Record<string, any>,
+): (...args: Parameters<T>) => ReturnType<T> | undefined;
+
+/**
+ * Validate a required value is defined and of the expected type.
+ * 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>;