@nisli/core 0.43.0

package/dist/emitter.js

@@ -0,0 +1,90 @@
+/**
+ * emitter.ts — Typed pub/sub base class for services.
+ *
+ * Replaces `document.dispatchEvent(new CustomEvent(...))` with typed,
+ * scoped event emitters. Services extend Emitter<T> where T defines
+ * the event contract as a record of event names → payload types.
+ *
+ * ```ts
+ * class NavigationEvents extends Emitter<{
+ *   select: { id: string };
+ *   filter: { filter: string };
+ * }> {}
+ *
+ * const nav = inject(NavigationEvents);
+ * nav.emit('select', { id: 'TASK-1' });           // typed
+ * nav.on('select', ({ id }) => console.log(id));   // typed
+ * const selectedId = nav.toSignal('select', e => e.id, null);
+ * ```
+ */
+import { signal } from './signal.js';
+import { hasContext, getCurrentComponent } from './context.js';
+// ── Emitter base class ──────────────────────────────────────────────
+export class Emitter {
+    listeners = new Map();
+    /**
+     * Emit a typed event. All subscribers for this event name are called
+     * synchronously. If a subscriber throws, other subscribers still fire.
+     */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        // Iterate a copy to allow unsubscribe during callback
+        for (const fn of [...set]) {
+            try {
+                fn(payload);
+            }
+            catch (err) {
+                console.error(`Emitter: subscriber for '${String(event)}' threw:`, err);
+            }
+        }
+    }
+    /**
+     * Subscribe to a typed event. Returns an unsubscribe function.
+     *
+     * If called during component setup, the subscription is automatically
+     * disposed on disconnectedCallback.
+     */
+    on(event, fn) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(fn);
+        const unsubscribe = () => {
+            set.delete(fn);
+            if (set.size === 0) {
+                this.listeners.delete(event);
+            }
+        };
+        // Auto-dispose if inside component setup context
+        if (hasContext()) {
+            getCurrentComponent().addDisposer(unsubscribe);
+        }
+        return unsubscribe;
+    }
+    /**
+     * Bridge an event into the signal system.
+     * Returns a signal that updates whenever the event fires.
+     *
+     * @param event - Event name to subscribe to
+     * @param selector - Transform the payload into the signal value
+     * @param initial - Initial signal value before any event fires
+     */
+    toSignal(event, selector, initial) {
+        const s = signal(initial);
+        this.on(event, (payload) => {
+            s.value = selector(payload);
+        });
+        return s;
+    }
+    /**
+     * Remove all subscribers. Useful for testing cleanup.
+     */
+    clear() {
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=emitter.js.map

package/dist/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAe,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAO/D,uEAAuE;AAEvE,MAAM,OAAO,OAAO;IACV,SAAS,GAAG,IAAI,GAAG,EAAoC,CAAC;IAEhE;;;OAGG;IACH,IAAI,CAAyB,KAAQ,EAAE,OAAkB;QACvD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG;YAAE,OAAO;QAEjB,sDAAsD;QACtD,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,EAAE,CAAC,OAAO,CAAC,CAAC;YACd,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,4BAA4B,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,EAAE,CAAyB,KAAQ,EAAE,EAAuB;QAC1D,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEZ,MAAM,WAAW,GAAG,GAAG,EAAE;YACvB,GAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAChB,IAAI,GAAI,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC,CAAC;QAEF,iDAAiD;QACjD,IAAI,UAAU,EAAE,EAAE,CAAC;YACjB,mBAAmB,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CACN,KAAQ,EACR,QAAmC,EACnC,OAAU;QAEV,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1B,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE;YACzB,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACX,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * packages/framework/ — Public API barrel export
+ *
+ * This is the single import point for all framework primitives.
+ *
+ * ```ts
+ * import {
+ *   signal, computed, effect, flush,
+ *   component, html, when,
+ *   inject, provide,
+ *   Emitter,
+ *   query, QueryClient,
+ * } from './framework';
+ * ```
+ */
+export { signal, computed, effect, flush, isSignal, flushEffects, untrack, SIGNAL_BRAND, type Signal, type ReadonlySignal, } from './signal.js';
+export { runWithContext, getCurrentComponent, hasContext, type ComponentHost, } from './context.js';
+export { Emitter } from './emitter.js';
+export { inject, provide, createToken, resetInjector, type Constructor, type InjectionToken, } from './injector.js';
+export { component, type ReactiveProps, type SetupFunction, type ComponentFactory, type ComponentOptions, type PropInput, type HostAttrs, } from './component.js';
+export { html, when, each, type TemplateResult, } from './template.js';
+export { ref, isRef, type Ref, } from './ref.js';
+export { onMount, onCleanup, useHostEvent, } from './lifecycle.js';
+export { query, QueryClient, type QueryResult, type QueryOptions, } from './query.js';

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * packages/framework/ — Public API barrel export
+ *
+ * This is the single import point for all framework primitives.
+ *
+ * ```ts
+ * import {
+ *   signal, computed, effect, flush,
+ *   component, html, when,
+ *   inject, provide,
+ *   Emitter,
+ *   query, QueryClient,
+ * } from './framework';
+ * ```
+ */
+// ── Reactivity ──────────────────────────────────────────────────────
+export { signal, computed, effect, flush, isSignal, flushEffects, untrack, SIGNAL_BRAND, } from './signal.js';
+// ── Setup context ───────────────────────────────────────────────────
+export { runWithContext, getCurrentComponent, hasContext, } from './context.js';
+// ── Typed event emitters ────────────────────────────────────────────
+export { Emitter } from './emitter.js';
+// ── Dependency injection ────────────────────────────────────────────
+export { inject, provide, createToken, resetInjector, } from './injector.js';
+// ── Component model ─────────────────────────────────────────────────
+export { component, } from './component.js';
+// ── Template engine ─────────────────────────────────────────────────
+export { html, when, each, } from './template.js';
+// ── Element refs ────────────────────────────────────────────────────
+export { ref, isRef, } from './ref.js';
+// ── Lifecycle hooks ─────────────────────────────────────────────────
+export { onMount, onCleanup, useHostEvent, } from './lifecycle.js';
+// ── Declarative data loading ────────────────────────────────────────
+export { query, QueryClient, } from './query.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,uEAAuE;AACvE,OAAO,EACL,MAAM,EACN,QAAQ,EACR,MAAM,EACN,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,YAAY,GAGb,MAAM,aAAa,CAAC;AAErB,uEAAuE;AACvE,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,UAAU,GAEX,MAAM,cAAc,CAAC;AAEtB,uEAAuE;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,uEAAuE;AACvE,OAAO,EACL,MAAM,EACN,OAAO,EACP,WAAW,EACX,aAAa,GAGd,MAAM,eAAe,CAAC;AAEvB,uEAAuE;AACvE,OAAO,EACL,SAAS,GAOV,MAAM,gBAAgB,CAAC;AAExB,uEAAuE;AACvE,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,IAAI,GAEL,MAAM,eAAe,CAAC;AAEvB,uEAAuE;AACvE,OAAO,EACL,GAAG,EACH,KAAK,GAEN,MAAM,UAAU,CAAC;AAElB,uEAAuE;AACvE,OAAO,EACL,OAAO,EACP,SAAS,EACT,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,uEAAuE;AACvE,OAAO,EACL,KAAK,EACL,WAAW,GAGZ,MAAM,YAAY,CAAC"}

package/dist/injector.d.ts

@@ -0,0 +1,65 @@
+/**
+ * injector.ts — Dependency injection: inject(), provide(), class-as-token
+ *
+ * Two key insights from Angular's evolution:
+ * 1. The class IS the token — no createToken() needed for 99% of cases
+ * 2. provide() is optional — inject() auto-creates singletons on first call
+ *
+ * ```ts
+ * class BacklogAPI {
+ *   async getTasks(): Promise<Task[]> { ... }
+ * }
+ *
+ * // In component setup:
+ * const api = inject(BacklogAPI); // auto-created singleton
+ *
+ * // In tests:
+ * provide(BacklogAPI, () => new MockAPI());
+ * ```
+ */
+/** Any class constructor — used as both the token and the type. */
+export type Constructor<T = unknown> = new (...args: any[]) => T;
+/** Opaque token for non-class dependencies (config objects, primitives). */
+export interface InjectionToken<T> {
+    readonly __brand: 'InjectionToken';
+    readonly name: string;
+    /** @internal default factory */
+    _factory?: () => T;
+}
+/**
+ * Get or create a singleton instance of the given class.
+ *
+ * On first call: creates the instance via `new Class()` (or the
+ * factory from provide(), if one exists). On subsequent calls:
+ * returns the same instance.
+ *
+ * Can be called inside or outside component setup context.
+ * When inside, the inject result is available for the component's lifetime.
+ */
+export declare function inject<T>(token: Constructor<T>): T;
+export declare function inject<T>(token: InjectionToken<T>): T;
+/**
+ * Register a factory override for a class or token.
+ * The factory will be called on the next inject() if no cached instance exists.
+ *
+ * Call provide() before the first inject() of that token.
+ * To override in tests, call resetInjector() first.
+ */
+export declare function provide<T>(token: Constructor<T>, factory: () => T): void;
+export declare function provide<T>(token: InjectionToken<T>, factory: () => T): void;
+/**
+ * Create an injection token for non-class dependencies.
+ * Use this for config objects, primitives, or interfaces.
+ *
+ * ```ts
+ * const AppConfig = createToken<{ apiUrl: string }>('AppConfig');
+ * provide(AppConfig, () => ({ apiUrl: '/api' }));
+ * const config = inject(AppConfig);
+ * ```
+ */
+export declare function createToken<T>(name: string, defaultFactory?: () => T): InjectionToken<T>;
+/**
+ * Reset the injector — clears all singletons and factory overrides.
+ * Used in tests to ensure isolation between test cases.
+ */
+export declare function resetInjector(): void;

package/dist/injector.js

@@ -0,0 +1,100 @@
+/**
+ * injector.ts — Dependency injection: inject(), provide(), class-as-token
+ *
+ * Two key insights from Angular's evolution:
+ * 1. The class IS the token — no createToken() needed for 99% of cases
+ * 2. provide() is optional — inject() auto-creates singletons on first call
+ *
+ * ```ts
+ * class BacklogAPI {
+ *   async getTasks(): Promise<Task[]> { ... }
+ * }
+ *
+ * // In component setup:
+ * const api = inject(BacklogAPI); // auto-created singleton
+ *
+ * // In tests:
+ * provide(BacklogAPI, () => new MockAPI());
+ * ```
+ */
+import { hasContext, getCurrentComponent } from './context.js';
+// ── Global singleton registry ───────────────────────────────────────
+/** Stores singleton instances keyed by constructor or token. */
+const singletonCache = new Map();
+/** Stores factory overrides from provide(). */
+const factoryOverrides = new Map();
+/** Tracks which constructors are currently being instantiated (circular detection). */
+const instantiating = new Set();
+export function inject(token) {
+    // Check cache first
+    if (singletonCache.has(token)) {
+        return singletonCache.get(token);
+    }
+    // Circular dependency detection
+    if (instantiating.has(token)) {
+        const name = typeof token === 'function' ? token.name : token.name;
+        throw new Error(`Circular dependency detected when instantiating '${name}'. ` +
+            'Check your service constructors for circular inject() calls.');
+    }
+    instantiating.add(token);
+    try {
+        let instance;
+        // Check for factory override
+        const factory = factoryOverrides.get(token);
+        if (factory) {
+            instance = factory();
+        }
+        else if (typeof token === 'function') {
+            // Class token — auto-create via constructor
+            instance = new token();
+        }
+        else {
+            // InjectionToken with default factory
+            const injToken = token;
+            if (injToken._factory) {
+                instance = injToken._factory();
+            }
+            else {
+                throw new Error(`No provider found for token '${injToken.name}'. ` +
+                    'Use provide() to register a factory before calling inject().');
+            }
+        }
+        singletonCache.set(token, instance);
+        return instance;
+    }
+    finally {
+        instantiating.delete(token);
+    }
+}
+export function provide(token, factory) {
+    factoryOverrides.set(token, factory);
+    // Remove cached instance so next inject() uses the new factory
+    singletonCache.delete(token);
+}
+/**
+ * Create an injection token for non-class dependencies.
+ * Use this for config objects, primitives, or interfaces.
+ *
+ * ```ts
+ * const AppConfig = createToken<{ apiUrl: string }>('AppConfig');
+ * provide(AppConfig, () => ({ apiUrl: '/api' }));
+ * const config = inject(AppConfig);
+ * ```
+ */
+export function createToken(name, defaultFactory) {
+    return {
+        __brand: 'InjectionToken',
+        name,
+        _factory: defaultFactory,
+    };
+}
+/**
+ * Reset the injector — clears all singletons and factory overrides.
+ * Used in tests to ensure isolation between test cases.
+ */
+export function resetInjector() {
+    singletonCache.clear();
+    factoryOverrides.clear();
+    instantiating.clear();
+}
+//# sourceMappingURL=injector.js.map

package/dist/injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injector.js","sourceRoot":"","sources":["../src/injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAe/D,uEAAuE;AAEvE,gEAAgE;AAChE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkD,CAAC;AAEjF,+CAA+C;AAC/C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAwD,CAAC;AAEzF,uFAAuF;AACvF,MAAM,aAAa,GAAG,IAAI,GAAG,EAAyC,CAAC;AAgBvE,MAAM,UAAU,MAAM,CAAI,KAAyC;IACjE,oBAAoB;IACpB,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,CAAM,CAAC;IACxC,CAAC;IAED,gCAAgC;IAChC,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,KAA2B,CAAC,IAAI,CAAC;QAC1F,MAAM,IAAI,KAAK,CACb,oDAAoD,IAAI,KAAK;YAC7D,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACzB,IAAI,CAAC;QACH,IAAI,QAAW,CAAC;QAEhB,6BAA6B;QAC7B,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAA8C,CAAC,CAAC;QACrF,IAAI,OAAO,EAAE,CAAC;YACZ,QAAQ,GAAG,OAAO,EAAO,CAAC;QAC5B,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;YACvC,4CAA4C;YAC5C,QAAQ,GAAG,IAAK,KAAwB,EAAE,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,sCAAsC;YACtC,MAAM,QAAQ,GAAG,KAA0B,CAAC;YAC5C,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACtB,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CACb,gCAAgC,QAAQ,CAAC,IAAI,KAAK;oBAClD,8DAA8D,CAC/D,CAAC;YACJ,CAAC;QACH,CAAC;QAED,cAAc,CAAC,GAAG,CAAC,KAA8C,EAAE,QAAQ,CAAC,CAAC;QAC7E,OAAO,QAAQ,CAAC;IAClB,CAAC;YAAS,CAAC;QACT,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAWD,MAAM,UAAU,OAAO,CAAI,KAAyC,EAAE,OAAgB;IACpF,gBAAgB,CAAC,GAAG,CAAC,KAA8C,EAAE,OAAO,CAAC,CAAC;IAC9E,+DAA+D;IAC/D,cAAc,CAAC,MAAM,CAAC,KAA8C,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAI,IAAY,EAAE,cAAwB;IACnE,OAAO;QACL,OAAO,EAAE,gBAAyB;QAClC,IAAI;QACJ,QAAQ,EAAE,cAAc;KACzB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,cAAc,CAAC,KAAK,EAAE,CAAC;IACvB,gBAAgB,CAAC,KAAK,EAAE,CAAC;IACzB,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * lifecycle.ts — Post-mount and cleanup lifecycle hooks
+ *
+ * `onMount()` registers a callback that runs after the component's
+ * template is mounted to the DOM. If the callback returns a function,
+ * that function runs on disconnect (cleanup).
+ *
+ * `onCleanup()` registers a standalone cleanup callback that runs
+ * on disconnect — for cases where you need cleanup without mount logic.
+ *
+ * Both must be called synchronously during component setup.
+ *
+ * ```ts
+ * component('my-el', (props, host) => {
+ *   onMount(() => {
+ *     host.querySelector('input')?.focus();
+ *     return () => console.log('unmounted');
+ *   });
+ *
+ *   onCleanup(() => clearInterval(timerId));
+ *
+ *   return html`<input />`;
+ * });
+ * ```
+ */
+/**
+ * Register a callback to run after the component's template is mounted.
+ * If the callback returns a function, it will be called on disconnect.
+ *
+ * Must be called synchronously during component setup.
+ */
+export declare function onMount(callback: () => void | (() => void)): void;
+/**
+ * Register a cleanup callback to run on disconnect.
+ * This is a convenience for cases where you need cleanup without mount logic.
+ *
+ * Must be called synchronously during component setup.
+ */
+export declare function onCleanup(callback: () => void): void;
+/**
+ * Listen for a DOM event on a target and auto-dispose the listener when the
+ * component disconnects. Works with any EventTarget (host element, document,
+ * window, etc.). Must be called during component setup.
+ *
+ * ```ts
+ * useHostEvent(host, 'click', (e) => {
+ *   // Runs on each click
+ * });
+ * ```
+ */
+export declare function useHostEvent<E extends Event = Event>(target: EventTarget, eventName: string, handler: (event: E) => void): void;
+/**
+ * Run all registered mount callbacks for a component host.
+ * Called by component.ts after the template is mounted to the DOM.
+ * @internal
+ */
+export declare function runMountCallbacks(comp: object): void;

package/dist/lifecycle.js

@@ -0,0 +1,107 @@
+/**
+ * lifecycle.ts — Post-mount and cleanup lifecycle hooks
+ *
+ * `onMount()` registers a callback that runs after the component's
+ * template is mounted to the DOM. If the callback returns a function,
+ * that function runs on disconnect (cleanup).
+ *
+ * `onCleanup()` registers a standalone cleanup callback that runs
+ * on disconnect — for cases where you need cleanup without mount logic.
+ *
+ * Both must be called synchronously during component setup.
+ *
+ * ```ts
+ * component('my-el', (props, host) => {
+ *   onMount(() => {
+ *     host.querySelector('input')?.focus();
+ *     return () => console.log('unmounted');
+ *   });
+ *
+ *   onCleanup(() => clearInterval(timerId));
+ *
+ *   return html`<input />`;
+ * });
+ * ```
+ */
+import { hasContext, getCurrentComponent } from './context.js';
+// ── Mount callback storage ──────────────────────────────────────────
+/** Mount callbacks are stored on the component host and called after template mount. */
+const mountCallbacks = new WeakMap();
+/**
+ * Register a callback to run after the component's template is mounted.
+ * If the callback returns a function, it will be called on disconnect.
+ *
+ * Must be called synchronously during component setup.
+ */
+export function onMount(callback) {
+    if (!hasContext()) {
+        throw new Error('onMount() called outside setup(). ' +
+            'It can only be called during component initialization.');
+    }
+    const comp = getCurrentComponent();
+    let callbacks = mountCallbacks.get(comp);
+    if (!callbacks) {
+        callbacks = [];
+        mountCallbacks.set(comp, callbacks);
+    }
+    callbacks.push(callback);
+}
+/**
+ * Register a cleanup callback to run on disconnect.
+ * This is a convenience for cases where you need cleanup without mount logic.
+ *
+ * Must be called synchronously during component setup.
+ */
+export function onCleanup(callback) {
+    if (!hasContext()) {
+        throw new Error('onCleanup() called outside setup(). ' +
+            'It can only be called during component initialization.');
+    }
+    getCurrentComponent().addDisposer(callback);
+}
+/**
+ * Listen for a DOM event on a target and auto-dispose the listener when the
+ * component disconnects. Works with any EventTarget (host element, document,
+ * window, etc.). Must be called during component setup.
+ *
+ * ```ts
+ * useHostEvent(host, 'click', (e) => {
+ *   // Runs on each click
+ * });
+ * ```
+ */
+export function useHostEvent(target, eventName, handler) {
+    if (!hasContext()) {
+        throw new Error('useHostEvent() called outside setup(). ' +
+            'It can only be called during component initialization.');
+    }
+    target.addEventListener(eventName, handler);
+    getCurrentComponent().addDisposer(() => {
+        target.removeEventListener(eventName, handler);
+    });
+}
+/**
+ * Run all registered mount callbacks for a component host.
+ * Called by component.ts after the template is mounted to the DOM.
+ * @internal
+ */
+export function runMountCallbacks(comp) {
+    const callbacks = mountCallbacks.get(comp);
+    if (!callbacks)
+        return;
+    for (const cb of callbacks) {
+        try {
+            const cleanup = cb();
+            if (typeof cleanup === 'function') {
+                // Register cleanup as a disposer on the component
+                comp.addDisposer(cleanup);
+            }
+        }
+        catch (err) {
+            console.error('onMount callback error:', err);
+        }
+    }
+    // Clear — mount callbacks run once
+    mountCallbacks.delete(comp);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAE/D,uEAAuE;AAEvE,wFAAwF;AACxF,MAAM,cAAc,GAAG,IAAI,OAAO,EAAyC,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,QAAmC;IACzD,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,oCAAoC;YACpC,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;IACnC,IAAI,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,EAAE,CAAC;QACf,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACtC,CAAC;IACD,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,QAAoB;IAC5C,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,sCAAsC;YACtC,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,mBAAmB,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAmB,EACnB,SAAiB,EACjB,OAA2B;IAE3B,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,yCAAyC;YACzC,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAwB,CAAC,CAAC;IAC7D,mBAAmB,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;QACrC,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAwB,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,SAAS;QAAE,OAAO;IAEvB,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC;YACrB,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;gBAClC,kDAAkD;gBACjD,IAAY,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,mCAAmC;IACnC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/query.d.ts

@@ -0,0 +1,81 @@
+/**
+ * query.ts — Declarative async data loading with cache
+ *
+ * `query()` absorbs the loading/error/cache/refetch boilerplate that
+ * every data-fetching component would otherwise write manually.
+ *
+ * Inspired by TanStack Query / React Query, but built on signals.
+ *
+ * ```ts
+ * const tasks = query(
+ *   () => ['tasks', scopeId.value],
+ *   () => api.getTasks(scopeId.value),
+ * );
+ * tasks.data      // Signal<Task[] | undefined>
+ * tasks.loading   // Signal<boolean>
+ * tasks.error     // Signal<Error | null>
+ * tasks.refetch() // manual refetch
+ * ```
+ */
+import { type Signal, type ReadonlySignal } from './signal.js';
+export interface QueryResult<T> {
+    /** The resolved data, or undefined if not yet loaded */
+    data: Signal<T | undefined>;
+    /** True while fetching */
+    loading: ReadonlySignal<boolean>;
+    /** The error if the fetch failed, null otherwise */
+    error: Signal<Error | null>;
+    /** Manually trigger a refetch */
+    refetch(): void;
+}
+export interface QueryOptions<T> {
+    /** Cache freshness duration in ms. Default: 0 (always refetch) */
+    staleTime?: number;
+    /** Number of retries on failure. Default: 0 */
+    retry?: number;
+    /** Skip fetch when returns false. Signal reads are tracked. */
+    enabled?: () => boolean;
+    /** Synchronous initial value before first fetch */
+    initialData?: T;
+    /** Callback after successful fetch */
+    onSuccess?: (data: T) => void;
+    /** Callback after failed fetch */
+    onError?: (error: Error) => void;
+}
+/**
+ * Global query cache. Managed as an auto-singleton via inject().
+ * Components use query() which accesses the client internally.
+ */
+export declare class QueryClient {
+    private cache;
+    private inFlight;
+    /** Check if a cache entry is fresh */
+    isFresh(key: string, staleTime: number): boolean;
+    /** Get cached data */
+    getCached<T>(key: string): T | undefined;
+    /** Store data in cache */
+    set(key: string, data: unknown, staleTime: number): void;
+    /** Get in-flight promise for deduplication */
+    getInFlight(key: string): Promise<unknown> | undefined;
+    /** Register an in-flight request */
+    setInFlight(key: string, promise: Promise<unknown>): void;
+    /**
+     * Invalidate cached entries whose key array starts with the given prefix elements.
+     * Returns the number of entries invalidated.
+     *
+     * invalidate(['tasks']) matches ['tasks'], ['tasks', '1'], ['tasks', '2', 'x']
+     */
+    invalidate(keyPrefix: unknown[]): number;
+    /** Prefetch and cache data */
+    prefetch(key: unknown[], fetcher: () => Promise<unknown>, staleTime?: number): Promise<void>;
+    /** Clear all cache */
+    clear(): void;
+}
+/**
+ * Declarative async data loading with caching and auto-refetch.
+ *
+ * @param keyFn - Returns a cache key array. Signal reads are auto-tracked for refetch.
+ * @param fetcher - Async function that fetches the data.
+ * @param options - Optional configuration (staleTime, retry, enabled, etc.)
+ */
+export declare function query<T>(keyFn: () => unknown[], fetcher: () => Promise<T>, options?: QueryOptions<T>): QueryResult<T>;