@nisli/core 0.54.1 → 0.55.0

package/dist/resource.d.ts

@@ -5,8 +5,9 @@
  * dependencies are tracked synchronously, while the loader runs outside the
  * reactive observer and commits only the newest live generation.
  */
+import { type DisposableResource } from './disposable.js';
 import { type ReadonlySignal } from './signal.js';
-export interface ResourceResult<T> {
+export interface ResourceResult<T> extends DisposableResource {
     /** Latest successful value. Retained while a newer load is pending. */
     readonly data: ReadonlySignal<T | undefined>;
     /** True while the current generation is loading. */

package/dist/resource.js

@@ -6,6 +6,8 @@
  * reactive observer and commits only the newest live generation.
  */
 import { getCurrentComponent, hasContext } from './context.js';
+import { disposable } from './disposable.js';
+import { __enrollPending } from './settle.js';
 import { effect, signal } from './signal.js';
 /**
  * Derive local async state from a synchronously tracked source.
@@ -63,32 +65,46 @@ export function resource(source, loader) {
         const isStale = () => (disposed
             || controller.signal.aborted
             || currentGeneration !== generation);
+        // settle() enrollment (ADR 0030.2 T2): this generation is a pending
+        // logical request from here until COMMIT (data/error write) or ABORT
+        // (the cleanup below) — never raw loader settlement, so an
+        // abort-ignoring loader cannot wedge settle(). Idempotent.
+        const settled = __enrollPending();
         // The microtask boundary is deliberate: loader signal reads are NOT source
         // dependencies, and synchronous loader throws become normal rejections.
         void Promise.resolve().then(async () => {
-            if (isStale())
+            if (isStale()) {
+                settled();
                 return;
+            }
             try {
                 const value = await loader(enabledSource, controller.signal);
-                if (isStale())
+                if (isStale()) {
+                    settled();
                     return;
+                }
                 data.value = value;
                 loading.value = false;
+                settled();
             }
             catch (cause) {
-                if (isStale())
+                if (isStale()) {
+                    settled();
                     return;
+                }
                 error.value = toError(cause);
                 loading.value = false;
+                settled();
             }
         });
         return () => {
             if (currentGeneration === generation)
                 generation++;
             controller.abort();
+            settled();
         };
     });
-    return {
+    const result = {
         data,
         loading,
         error,
@@ -98,6 +114,7 @@ export function resource(source, loader) {
         },
         dispose,
     };
+    return disposable(result, dispose);
 }
 function toError(cause) {
     if (cause instanceof Error)

package/dist/resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}

package/dist/settle.d.ts

@@ -0,0 +1,61 @@
+/**
+ * settle.ts — Awaitable async quiescence (ADR 0030.2 T2).
+ *
+ * `await settle()` resolves when every framework-started logical async
+ * request has TERMINATED and the reactive graph is quiescent. Query runs
+ * (query.ts) and resource loads (resource.ts) enroll here when they start
+ * and deregister at *termination* — commit, terminal error after retries,
+ * or abort — never at raw promise settlement. An abort-ignoring fetcher
+ * whose run was superseded therefore cannot wedge `settle()`: the run's
+ * registry entry closed at the abort even though the underlying promise
+ * never resolves.
+ *
+ * ```ts
+ * mount(app);
+ * await settle();
+ * expect(screen.textContent).toContain('loaded');   // no waitFor polling
+ * ```
+ *
+ * Contract and bounds:
+ * - This is a **test/verify primitive** (and the SSG pre-snapshot barrier).
+ *   Awaiting it in a live app with continuous background refetch/polling is
+ *   unbounded *by design* — each commit may legally schedule the next
+ *   request. A scope argument waits for a second consumer (ADR 0030.2 §8).
+ * - Each iteration awaits the pending registry, then `tick()` (signal.ts's
+ *   bounded microtask-drain contract). Timer-scheduled work is NOT awaited
+ *   beyond what a pending logical request itself spans.
+ * - Iteration-capped at 50 like `tick()`; hitting the cap emits diagnostic
+ *   N603 and resolves — never a silent hang, never an unbounded loop.
+ *
+ * MERGE ITEM: `__resetPending()` should be folded into `resetInjector()`
+ * (injector.ts is owned by another worktree); until then test teardown
+ * calls it directly.
+ */
+/**
+ * Enroll a logical async request. Returns its `done()` terminator: call it
+ * at commit, terminal error, or abort. Idempotent — a superseded run whose
+ * terminator was already invoked by the superseding path may safely call
+ * it again from its own settlement branch.
+ *
+ * @internal — called by query.ts runs and resource.ts loader generations.
+ */
+export declare function __enrollPending(): () => void;
+/**
+ * Reset the registry. Test-teardown escape hatch: entries orphaned by a
+ * test that never terminated its fetchers would otherwise leak into the
+ * next test's `settle()`.
+ *
+ * @internal
+ */
+export declare function __resetPending(): void;
+/** Current number of enrolled (unterminated) logical requests. @internal */
+export declare function __pendingCount(): number;
+/**
+ * Await async quiescence: loop `tick()` → `Promise.allSettled(pending)`
+ * until a full `tick()` leaves the pending registry empty.
+ *
+ * The `tick()` *first* ordering matters: observer effects created since
+ * the last flush are what *start* runs (and enroll them) — the registry
+ * can only be trusted empty after the reactive graph has flushed.
+ */
+export declare function settle(): Promise<void>;

package/dist/settle.js

@@ -0,0 +1,106 @@
+/**
+ * settle.ts — Awaitable async quiescence (ADR 0030.2 T2).
+ *
+ * `await settle()` resolves when every framework-started logical async
+ * request has TERMINATED and the reactive graph is quiescent. Query runs
+ * (query.ts) and resource loads (resource.ts) enroll here when they start
+ * and deregister at *termination* — commit, terminal error after retries,
+ * or abort — never at raw promise settlement. An abort-ignoring fetcher
+ * whose run was superseded therefore cannot wedge `settle()`: the run's
+ * registry entry closed at the abort even though the underlying promise
+ * never resolves.
+ *
+ * ```ts
+ * mount(app);
+ * await settle();
+ * expect(screen.textContent).toContain('loaded');   // no waitFor polling
+ * ```
+ *
+ * Contract and bounds:
+ * - This is a **test/verify primitive** (and the SSG pre-snapshot barrier).
+ *   Awaiting it in a live app with continuous background refetch/polling is
+ *   unbounded *by design* — each commit may legally schedule the next
+ *   request. A scope argument waits for a second consumer (ADR 0030.2 §8).
+ * - Each iteration awaits the pending registry, then `tick()` (signal.ts's
+ *   bounded microtask-drain contract). Timer-scheduled work is NOT awaited
+ *   beyond what a pending logical request itself spans.
+ * - Iteration-capped at 50 like `tick()`; hitting the cap emits diagnostic
+ *   N603 and resolves — never a silent hang, never an unbounded loop.
+ *
+ * MERGE ITEM: `__resetPending()` should be folded into `resetInjector()`
+ * (injector.ts is owned by another worktree); until then test teardown
+ * calls it directly.
+ */
+import { tick } from './signal.js';
+// ── Pending logical-request registry ────────────────────────────────
+/**
+ * One entry per in-flight logical request. The promise is a *termination*
+ * promise resolved by the enroller's `done()` callback — deliberately not
+ * the fetcher/loader promise itself (see module doc).
+ */
+const pending = new Set();
+/**
+ * Enroll a logical async request. Returns its `done()` terminator: call it
+ * at commit, terminal error, or abort. Idempotent — a superseded run whose
+ * terminator was already invoked by the superseding path may safely call
+ * it again from its own settlement branch.
+ *
+ * @internal — called by query.ts runs and resource.ts loader generations.
+ */
+export function __enrollPending() {
+    let resolve;
+    const entry = new Promise((res) => { resolve = res; });
+    pending.add(entry);
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        pending.delete(entry);
+        resolve();
+    };
+}
+/**
+ * Reset the registry. Test-teardown escape hatch: entries orphaned by a
+ * test that never terminated its fetchers would otherwise leak into the
+ * next test's `settle()`.
+ *
+ * @internal
+ */
+export function __resetPending() {
+    pending.clear();
+}
+/** Current number of enrolled (unterminated) logical requests. @internal */
+export function __pendingCount() {
+    return pending.size;
+}
+// ── Diagnostics + test isolation ────────────────────────────────────
+// Reporting goes through the core diagnostics leaf. The pending registry
+// self-registers with resetInjector() so test teardown clears it without
+// an upside-down import (settle → injector, never the reverse).
+import { diag, isDev } from './diagnostics.js';
+import { registerResetHook } from './injector.js';
+registerResetHook(__resetPending);
+// ── settle() ────────────────────────────────────────────────────────
+/**
+ * Await async quiescence: loop `tick()` → `Promise.allSettled(pending)`
+ * until a full `tick()` leaves the pending registry empty.
+ *
+ * The `tick()` *first* ordering matters: observer effects created since
+ * the last flush are what *start* runs (and enroll them) — the registry
+ * can only be trusted empty after the reactive graph has flushed.
+ */
+export async function settle() {
+    for (let i = 0; i < 50; i++) {
+        await tick();
+        if (pending.size === 0)
+            return;
+        await Promise.allSettled([...pending]);
+    }
+    if (isDev())
+        diag('N603', 'settle() did not reach quiescence within 50 iterations — something '
+            + 'keeps scheduling new async work (a self-invalidating query or a '
+            + 'polling loop?). settle() is a test/verify primitive; under live '
+            + 'background refetch it is unbounded by design. Returning anyway.');
+}
+//# sourceMappingURL=settle.js.map

package/dist/settle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../src/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,uEAAuE;AAEvE;;;;GAIG;AACH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,OAAoB,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACnB,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,OAAO,GAAG,EAAE;QACV,IAAI,IAAI;YAAE,OAAO;QACjB,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,gEAAgE;AAChE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD,iBAAiB,CAAC,cAAc,CAAC,CAAC;AAElC,uEAAuE;AAEvE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,EAAE,CAAC;QACb,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,KAAK,EAAE;QAAE,IAAI,CACf,MAAM,EACN,qEAAqE;cACnE,kEAAkE;cAClE,kEAAkE;cAClE,iEAAiE,CACpE,CAAC;AACJ,CAAC"}

package/dist/signal.d.ts

@@ -2,10 +2,26 @@
  * signal.ts — Reactive primitives: signal(), computed(), effect()
  *
  * Push-pull hybrid model:
- * - Writes push "dirty" flags up the dependency graph
+ * - Writes push dirty flags up the dependency graph in two flavors: a signal
+ *   write pushes Dirty (the value definitely changed), a computed propagates
+ *   MaybeDirty (recompute to find out). Flags never downgrade.
  * - Reads pull fresh values lazily (computed only recalculates when read)
  * - Multiple synchronous writes coalesce into one microtask flush
  *
+ * Scheduler invariants (ADR 0030.2 T5):
+ * - An effect re-runs iff a value it read changed. Before a MaybeDirty
+ *   effect runs, its computed sources are polled (recomputed via the
+ *   node→impl back-pointer); if no source's change-epoch advanced past the
+ *   effect's last completed run, the run is skipped. A computed's
+ *   change-epoch also bumps on every error-state TRANSITION (enter and
+ *   exit), so effects never skip across error entry or equal-value recovery
+ *   (issue 0003 containment happens at the effect's own read).
+ * - Pending effects flush in creation order (monotonic index), so identical
+ *   writes produce identical run order. Documented cost: a later-created
+ *   writer effect costs one deterministic extra run vs. topological order.
+ * - The loop guard is clock-free: an effect that re-schedules ITSELF on
+ *   MAX_EFFECT_RERUNS consecutive runs is diagnosed (N301) and disposed.
+ *
  * Dependency tracking is automatic: reading a signal inside a computed
  * or effect registers it as a dependency. Dependencies are re-tracked
  * on every execution (dynamic/conditional tracking).
@@ -21,12 +37,21 @@ export interface ReadonlySignal<T> {
     readonly [SIGNAL_BRAND]: true;
     readonly value: T;
     /** Subscribe to value changes. Returns unsubscribe function. */
-    subscribe(fn: (value: T) => void): () => void;
+    subscribe(fn: (value: T) => void): Disposer;
+    /**
+     * Read the current value WITHOUT registering a dependency.
+     * Equivalent to reading inside `untrack()`. On a computed this still
+     * pulls a fresh value (and rethrows a cached error) — it only skips
+     * dependency registration.
+     */
+    peek(): T;
 }
 /** Read-write reactive container. */
 export interface Signal<T> extends ReadonlySignal<T> {
     value: T;
 }
+import { type Disposer } from './disposable.js';
+export type { Disposer } from './disposable.js';
 /**
  * Create a writable reactive signal.
  *
@@ -34,6 +59,7 @@ export interface Signal<T> extends ReadonlySignal<T> {
  * const count = signal(0);
  * count.value;     // read (auto-tracks in reactive contexts)
  * count.value = 5; // write (notifies dependents)
+ * count.peek();    // read WITHOUT tracking
  * ```
  */
 export declare function signal<T>(initialValue: T): Signal<T>;
@@ -47,12 +73,20 @@ export declare function signal<T>(initialValue: T): Signal<T>;
  * ```
  */
 export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
+/**
+ * Type-level rejection of async callbacks: a Promise-returning fn makes the
+ * call require an impossible second argument, so `effect(async () => {})`
+ * fails to compile. Async work belongs in resource() (ADR 0030.2 §3; N310).
+ */
+type SyncEffectGuard<R> = [R] extends [Promise<unknown>] ? [error: 'effect() callbacks must be synchronous — async work belongs in resource() (nisli N310)'] : [];
 /**
  * Create a side-effect that re-runs when its dependencies change.
  * Returns a dispose function to stop the effect.
  *
  * The effect function may return a cleanup callback that runs
- * before each re-execution and on disposal.
+ * before each re-execution and on disposal. It must be SYNCHRONOUS —
+ * async functions are rejected at the type level and diagnosed at
+ * runtime (N310); async state belongs in resource().
  *
  * ```ts
  * const dispose = effect(() => {
@@ -64,7 +98,7 @@ export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
  * dispose(); // stop the effect
  * ```
  */
-export declare function effect(fn: () => void | (() => void)): () => void;
+export declare function effect<R>(fn: () => R, ..._rejectAsync: SyncEffectGuard<R>): Disposer;
 /**
  * Check if a value is a signal (writable or computed).
  * Used by the template engine to detect signals in expression slots.
@@ -72,13 +106,14 @@ export declare function effect(fn: () => void | (() => void)): () => void;
 export declare function isSignal(value: unknown): value is ReadonlySignal<unknown>;
 /**
  * Run a function with activeObserver set to null, preventing any
- * signal reads inside `fn` from being tracked by an outer effect.
+ * signal reads inside `fn` from being tracked by an outer effect,
+ * and return the function's result.
  *
  * Used by component.ts to isolate connectedCallback: child component
  * setup signal reads must not leak into a parent effect's dependency
  * set. See ADR 0008 Gap 1.
  */
-export declare function untrack(fn: () => void): void;
+export declare function untrack<T>(fn: () => T): T;
 /**
  * Synchronously execute all pending effects.
  *
@@ -102,7 +137,7 @@ export { flush as flushEffects };
  * TASKS scheduled by that microtask work (e.g. a microtask calling
  * setTimeout) may fire after tick() resolves; awaiting arbitrary future
  * tasks is unbounded. Self-perpetuating schedulers are cut off at the
- * iteration cap.
+ * iteration cap (loudly — N303).
  *
  * ```ts
  * host.setProp('x', 1);