effectweb 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # effectweb
 
-Immutable Effect models and JSX compiled to direct DOM updates, without signals, proxies, or virtual DOM.
+Immutable Effect models and JSX with direct DOM rendering.
 
 Use with `@effectweb/compiler/vite` and Effect `4.0.0-rc.112`. The package includes programs, named tasks, async presentation, query caching, DOM lifetimes, and `effectweb/testing` helpers.
 
@@ -8,6 +8,37 @@ See [setup and example](https://github.com/DerpyCrabs/EffectWeb#vite-setup).
 
 Runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.
 
+## Views and list identity
+
+`view(render)` evaluates `render(model, send)` as ordinary JavaScript on each immutable model publication. Calls, local variables, destructuring, loops, conditionals, and JSX helpers retain their JavaScript behavior. The renderer reconciles the returned content; the compiler does not infer dependencies or cache helper results.
+
+Use `list(rows, render)` to preserve domain identity:
+
+```tsx
+import { entities, list, view } from 'effectweb';
+
+type Todo = { id: string; title: string };
+const Todos = view<{ todos: Todo[] }>((model) => (
+  <ul>
+    {list(entities(model.todos), (todo) => (
+      <li>{todo.title}</li>
+    ))}
+  </ul>
+));
+```
+
+`collection(identity).from(items)` supplies a custom domain identity; `sequence(items)` supplies positional identity. `list(rawArray, render)` uses each item itself as its identity, so repeated values or references require an explicit collection identity. Duplicate identities throw with both positions. The callback receives the exact current item, including a replacement object with the same ID. `Rows.map` and ordinary array `.map` remain normal JavaScript mapping operations; their rendered arrays use positional identity.
+
+`slot(render)` is a typed render callback. Call it explicitly, including `footer()` for a `Slot<void>`; a function is not implicit JSX content. See the [0.4.0 migration guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/migration-0.4.0.md).
+
+## DOM and Effect lifetimes
+
+`domMount(acquire)` uses the acquisition function as its identity. Declare it outside the view body when its lifetime should survive model updates. `domBinding(data, acquire)` keeps a stable acquisition while supplying fresh data through `input()`. Return `{ update, dispose }` when the integration must apply changed data, or a scoped Effect that remains active for the lifetime. A new acquisition function replaces the old lifetime.
+
+Fresh event callbacks see current model data without canceling already running listener work. An Effect event's `replace` policy cancels the previous request when a new event submits work; removing the handler or unmounting disposes its owned work.
+
+`dispose()` interrupts owned work synchronously. `close()`, `awaitIdle()`, and `awaitStopped()` return Effects; merely creating or JavaScript-awaiting one does not execute it. Use `yield* owner.close()` inside an Effect or `await Effect.runPromise(owner.close())` at a Promise integration boundary. `close()` waits for finalizers; `awaitIdle()` waits without closing the owner. A mount returned by `mountView` also has `close()` for its DOM-owned work. The supplied program keeps its separate ownership.
+
 ## Query identity and account ownership
 
 A query definition has its own identity. Within one cache, all request arguments form its key automatically:
@@ -76,7 +107,7 @@ Queue progress continues after successes, typed failures, or defects. Component
 
 `<Portal mount={model.dialogHost}>...</Portal>` renders into a supplied HTML or SVG element. Omitting `mount` uses the document body. Portal content retains its owner, events, and cleanup; changing between HTML and SVG targets rebuilds content in the correct namespace.
 
-## Inspect source dependencies
+## Inspect source bindings
 
 Mount a development panel before mounting the application so it sees initial evaluations:
 
@@ -88,11 +119,11 @@ const removeInspector = mountBindingInspector(document.querySelector<HTMLElement
 // removeInspector();
 ```
 
-The live, filterable table shows original file/line/column, source expressions, inferred snapshot dependencies, the latest changed dependency names, and derive/binding evaluation counts. It uses development compiler metadata; production builds emit none. Counts include initial evaluations, aggregate instances of the same source expression, and measure evaluations rather than actual DOM writes. Change reasons use reference/value equality, without retaining previous or next values.
+The live, filterable table shows original file/line/column, source expressions, and binding evaluation counts. Development metadata records the expressions actually evaluated for text and attributes; it does not infer which model fields a helper reads. Production builds emit none. Counts include initial evaluations, aggregate instances of the same source expression, and measure binding evaluations rather than DOM writes. Change reasons compare evaluated values without retaining previous or next values.
 
 For custom tooling, `inspectBindings({ limit: 200 })` returns `entries()`, `subscribe(listener)`, `clear()`, and `dispose()`. Entries are immutable metadata, newest first, with at most 1000 source records. Least recently updated sources are evicted and start fresh if seen again. `dispose()` unsubscribes and clears retained metadata. `mountBindingInspector(element, inspector)` can share an inspector; removing that panel leaves the supplied inspector running. Low-level `observeBindings` remains available.
 
-The inspector covers instrumented derivations and text/attribute bindings; it is not a snapshot recorder, time-travel debugger, or complete profile of branch/list reconciliation. Source labels describe the compiler's inferred dependencies, not a proof that an opaque helper has no hidden state.
+The inspector covers instrumented text/attribute bindings; it is not a snapshot recorder, time-travel debugger, or complete profile of view evaluation and list reconciliation. Use application profiling for expensive render helpers.
 
 ## Immutable inputs and outputs
 

package/dist/AsyncContent.d.ts

@@ -1,4 +1,4 @@
-import { Cause } from 'effect';
+import * as Cause from 'effect/Cause';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import { type Slot, type View } from './index.js';
 import type { JSX } from './jsx.js';

package/dist/AsyncContent.js

@@ -1,6 +1,8 @@
 import * as _ew_dom from "./dom.js";
 import { commandSlot } from "./program.js";
-import { Cause, Effect, Option } from "effect";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import { component } from "./component.js";
 import { view } from "./index.js";
@@ -47,40 +49,21 @@ const implementation = component({
             ...model,
             visible: true
         } }),
-    view: /* @__PURE__ */ _ew_dom.compiled((_ew_scope_1, _ew_parent_2, _ew_before_3) => {
-        const _ew_derived_4 = _ew_scope_1.derive(() => [_ew_scope_1.value?.props], () => {
-            const _ew_capture_6 = _ew_scope_1.value;
-            return _ew_capture_6.props;
-        });
-        const _ew_derived_7 = _ew_scope_1.derive(() => [_ew_derived_4()?.result], () => {
-            const _ew_capture_9 = _ew_derived_4();
-            return AsyncResult.value(_ew_capture_9.result);
-        });
-        const _ew_derived_10 = _ew_scope_1.derive(() => [_ew_derived_4()?.result, _ew_derived_4()?.result?.waiting], () => {
-            const _ew_capture_12 = _ew_derived_4();
-            return AsyncResult.isFailure(_ew_capture_12.result) && !_ew_capture_12.result.waiting ? _ew_capture_12.result : undefined;
-        });
-        _ew_dom.branch(_ew_scope_1, _ew_parent_2, _ew_before_3, () => Option.isSome(_ew_derived_7()), (_ew_scope_1, _ew_parent_13, _ew_before_14) => {
-            _ew_dom.text(_ew_scope_1, _ew_parent_13, _ew_before_14, () => [_ew_derived_4(), _ew_derived_7()?.value], () => _ew_derived_4().content(_ew_derived_7().value));
-            _ew_dom.branch(_ew_scope_1, _ew_parent_13, _ew_before_14, () => _ew_derived_4().result.waiting, (_ew_scope_1, _ew_parent_15, _ew_before_16) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_15, _ew_before_16, () => [_ew_derived_4()?.refreshing], () => _ew_derived_4().refreshing);
-            }, (_ew_scope_1, _ew_parent_15, _ew_before_16) => { });
-            _ew_dom.branch(_ew_scope_1, _ew_parent_13, _ew_before_14, () => _ew_derived_10() && _ew_derived_4().failure, (_ew_scope_1, _ew_parent_17, _ew_before_18) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_17, _ew_before_18, () => [_ew_derived_4(), _ew_derived_10()?.cause], () => _ew_derived_4().failure(_ew_derived_10().cause));
-            }, (_ew_scope_1, _ew_parent_17, _ew_before_18) => { });
-        }, (_ew_scope_1, _ew_parent_13, _ew_before_14) => {
-            _ew_dom.branch(_ew_scope_1, _ew_parent_13, _ew_before_14, () => _ew_derived_10() && _ew_derived_4().failure, (_ew_scope_1, _ew_parent_19, _ew_before_20) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_19, _ew_before_20, () => [_ew_derived_4(), _ew_derived_10()?.cause], () => _ew_derived_4().failure(_ew_derived_10().cause));
-            }, (_ew_scope_1, _ew_parent_19, _ew_before_20) => {
-                _ew_dom.branch(_ew_scope_1, _ew_parent_19, _ew_before_20, () => _ew_scope_1.value.pending, (_ew_scope_1, _ew_parent_21, _ew_before_22) => {
-                    _ew_dom.branch(_ew_scope_1, _ew_parent_21, _ew_before_22, () => _ew_scope_1.value.visible, (_ew_scope_1, _ew_parent_23, _ew_before_24) => {
-                        _ew_dom.text(_ew_scope_1, _ew_parent_23, _ew_before_24, () => [_ew_derived_4()?.pending], () => _ew_derived_4().pending);
-                    }, (_ew_scope_1, _ew_parent_23, _ew_before_24) => { });
-                }, (_ew_scope_1, _ew_parent_21, _ew_before_22) => {
-                    _ew_dom.text(_ew_scope_1, _ew_parent_21, _ew_before_22, () => [_ew_derived_4()?.empty], () => _ew_derived_4().empty);
-                });
-            });
-        });
+    view: view((model, _send) => {
+        const props = model.props;
+        const data = AsyncResult.value(props.result);
+        const failure = AsyncResult.isFailure(props.result) && !props.result.waiting ? props.result : undefined;
+        if (Option.isSome(data))
+            return [
+                props.content(data.value),
+                props.result.waiting ? props.refreshing : null,
+                failure && props.failure ? props.failure(failure.cause) : null
+            ];
+        if (failure && props.failure)
+            return props.failure(failure.cause);
+        if (model.pending)
+            return model.visible ? props.pending : null;
+        return props.empty;
     })
 });
 /** Presentation only: resource owners choose identity, loading, caching and cancellation. */

package/dist/boundary.d.ts

@@ -0,0 +1,11 @@
+import { type View } from './dom.js';
+import { type ReportError } from './errors.js';
+import { type Snapshot } from './snapshot.js';
+export declare function errorBoundary<Model, Message>(content: View<Model, Message>, options: {
+    readonly fallback: View<{
+        readonly model: NoInfer<Model>;
+        readonly error: unknown;
+    }, NoInfer<Message>>;
+    readonly reset?: (model: Snapshot<NoInfer<Model>>) => unknown;
+    readonly onError?: ReportError;
+}): View<Model, Message>;

package/dist/boundary.js

@@ -0,0 +1,66 @@
+import { child, compiled, viewRegion } from './dom.js';
+import { reportError, reportSafely } from './errors.js';
+import { protectSnapshot } from './snapshot.js';
+export function errorBoundary(content, options) {
+    return compiled((scope, parent, before) => {
+        let failed = false;
+        let error;
+        let generation = 0;
+        let reset = options.reset?.(scope.value);
+        const fallback = compiled((scope, parent, before) => {
+            child(scope, parent, before, options.fallback, () => [scope.value], () => protectSnapshot({ model: scope.value, error }), scope.send);
+        });
+        const region = { manual: true, report: scope.report };
+        const render = viewRegion(scope, parent, before, region);
+        function showFallback() {
+            if (scope.disposed || !failed)
+                return;
+            region.report = scope.report;
+            try {
+                render(fallback);
+            }
+            catch (error) {
+                reportSafely(scope.report, error);
+            }
+        }
+        function fail(cause, attempt) {
+            if (scope.disposed || attempt !== generation) {
+                reportSafely(options.onError ?? reportError, cause);
+                return;
+            }
+            failed = true;
+            error = cause;
+            const token = ++generation;
+            render(undefined);
+            reportSafely(options.onError ?? reportError, cause);
+            queueMicrotask(() => {
+                if (token === generation)
+                    showFallback();
+            });
+        }
+        const update = () => {
+            const next = options.reset?.(scope.value);
+            if (!Object.is(reset, next)) {
+                reset = next;
+                generation++;
+                render(undefined);
+                failed = false;
+                error = undefined;
+            }
+            if (failed)
+                showFallback();
+            else {
+                const attempt = generation;
+                region.report = (cause) => fail(cause, attempt);
+                try {
+                    render(content);
+                }
+                catch (error) {
+                    fail(error, attempt);
+                }
+            }
+        };
+        scope.jobs.push(update);
+        update();
+    });
+}

package/dist/cache-internals.d.ts

@@ -5,6 +5,10 @@ import type { QueryCache } from './cache.js';
 import type { Query } from './query.js';
 import type { Snapshot } from './snapshot.js';
 export interface CacheInternals<R> {
+    refresh(atom: Atom.Atom<unknown>): void;
+    readonly disposed: () => boolean;
+    revision<Args, A, E>(definition: Query<Args, A, E, R>, args: Args | Snapshot<Args>): number | undefined;
+    retain(atom: Atom.Atom<unknown>): () => void;
     readonly registry: AtomRegistry.AtomRegistry;
     readonly generation: Atom.Writable<number>;
     query<Args, A, E>(definition: Query<Args, A, E, R>, args: Args | Snapshot<Args>): Atom.Atom<AsyncResult.AsyncResult<Snapshot<A>, E>>;

package/dist/cache.d.ts

@@ -1,14 +1,28 @@
 import { type Snapshot } from './snapshot.js';
-import { Effect } from 'effect';
-import { type Query } from './query.js';
+import * as Effect from 'effect/Effect';
+import { type Query, type QueryGroup } from './query.js';
 import type { UiRuntime } from './runtime.js';
 export { loadEffect, type UiLoad } from './load.js';
 export { shareValue } from './share.js';
-export declare function makeQueryCache(): QueryCache<never>;
-export declare function makeQueryCache<R>(runtime: UiRuntime<R>): QueryCache<R>;
+export interface QueryCacheOptions {
+    readonly retention?: number;
+    readonly unused?: 'retain' | 'cancel' | undefined;
+}
+export declare function makeQueryCache(options?: QueryCacheOptions): QueryCache<never>;
+export declare function makeQueryCache<R>(runtime: UiRuntime<R>, options?: QueryCacheOptions): QueryCache<R>;
 /** A cache owns one registry and the query resources published through it. */
 export interface QueryCache<R = never> {
-    prefetch<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>): Effect.Effect<Snapshot<A>, E>;
+    batch(work: () => void): void;
+    getQueryData<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>): Snapshot<A> | undefined;
+    invalidateWhere<Args, A, E>(definition: Query<Args, A, E, R>, predicate: (args: Snapshot<Args>) => boolean): void;
+    invalidateGroup(group: QueryGroup): void;
+    /** Cancel requests while retaining the last success. Explicit refresh restarts them. */
+    cancelQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [NoInfer<Args> | Snapshot<NoInfer<Args>>]): void;
+    /** Clear cached data and cancel requests; a subsequent selection or refresh reloads. */
+    removeQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [NoInfer<Args> | Snapshot<NoInfer<Args>>]): void;
+    prefetch<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>, options?: {
+        readonly refresh?: boolean;
+    }): Effect.Effect<Snapshot<A>, E>;
     /** Publish a protected success, including undefined, and supersede any pending load for this key. */
     setQueryData<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>, value: NoInfer<A> | Snapshot<NoInfer<A>>): Snapshot<A>;
     /**
@@ -21,5 +35,7 @@ export interface QueryCache<R = never> {
     /** Observe account resets without exposing registry mutation. */
     onReset(listener: () => void): () => void;
     resetResources(): void;
+    /** Interrupt every request and wait for its finalizers, including previously canceled requests. */
+    close(): Effect.Effect<void>;
     dispose(): void;
 }

package/dist/cache.js

@@ -1,5 +1,8 @@
+import { Settlement } from './settlement.js';
 import { protectSnapshot } from './snapshot.js';
-import { Effect, Option } from 'effect';
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import * as Atom from 'effect/unstable/reactivity/Atom';
 import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
@@ -10,18 +13,29 @@ import { registerCache } from './cache-internals.js';
 import { queryDefinition } from './query-internals.js';
 export { loadEffect } from './load.js';
 export { shareValue } from './share.js';
-export function makeQueryCache(runtime) {
-    return createQueryCache(runtime);
+export function makeQueryCache(runtimeOrOptions, options = {}) {
+    return runtimeOrOptions && 'provide' in runtimeOrOptions
+        ? createQueryCache(runtimeOrOptions, options)
+        : createQueryCache(undefined, runtimeOrOptions);
 }
-function createQueryCache(runtime) {
-    const registry = AtomRegistry.make({ defaultIdleTTL: 30_000 });
+function createQueryCache(runtime, options = {}) {
+    const retention = options.retention ?? 30_000;
+    if (!Number.isFinite(retention) || retention < 0)
+        throw new RangeError('Query retention must be finite and nonnegative.');
+    const registry = AtomRegistry.make({ defaultIdleTTL: retention });
+    const cancelValue = Symbol('cancel');
+    const removeValue = Symbol('remove');
     const generation = Atom.keepAlive(Atom.make(0));
     const resources = new Map();
+    const entriesByAtom = new WeakMap();
     // Follow registry-node lifetime; retaining definitions must not retain evicted data.
     const values = new WeakMap();
     const identities = new WeakMap();
     let disposed = false;
+    const settlement = new Settlement();
+    let closing;
     let nextId = 0;
+    let nextRevision = 0;
     const identity = (definition) => {
         let id = identities.get(definition);
         if (id === undefined) {
@@ -37,28 +51,54 @@ function createQueryCache(runtime) {
         else {
             const loaded = Atom.make((get) => {
                 const previous = Option.flatMap(get.self(), AsyncResult.value);
-                return loadEffect(() => next.load()).pipe(Effect.map((value) => {
-                    const shared = Option.isSome(previous)
-                        ? share(previous.value, value)
-                        : value;
-                    const snapshot = protectSnapshot(shared);
-                    remember(next, snapshot);
-                    return snapshot;
-                }));
+                next.revision = ++nextRevision;
+                next.canceled = false;
+                const revision = next.revision;
+                return Effect.suspend(() => {
+                    const finish = settlement.begin();
+                    return loadEffect(() => next.load()).pipe(Effect.map((value) => {
+                        const shared = Option.isSome(previous)
+                            ? share(previous.value, value)
+                            : value;
+                        const snapshot = protectSnapshot(shared);
+                        if (!disposed && revision === next.revision)
+                            remember(next, snapshot);
+                        return snapshot;
+                    }), Effect.ensuring(Effect.sync(finish)));
+                });
             });
             const next = {
                 load,
+                users: 0,
+                prefetches: new Set(),
+                revision: 0,
                 atom: Atom.writable(loaded.read, (context, value) => {
                     Atom.batch(() => {
+                        next.revision = ++nextRevision;
                         // Refresh disposes the load lifetime; setSelf publishes without starting another load.
                         context.refreshSelf();
-                        remember(next, value);
-                        context.setSelf(AsyncResult.success(value));
+                        if (value === cancelValue || value === removeValue) {
+                            const previous = value === removeValue ? undefined : previousValue(next);
+                            next.canceled = true;
+                            if (value === removeValue) {
+                                delete next.loadedAt;
+                                const node = registry.getNodes().get(next.atom);
+                                if (node)
+                                    values.delete(node);
+                            }
+                            context.setSelf(previous ? AsyncResult.success(previous.value) : AsyncResult.initial());
+                        }
+                        else {
+                            next.canceled = false;
+                            remember(next, value);
+                            context.setSelf(AsyncResult.success(value));
+                        }
                     });
                 }),
             };
             entry = next;
             resources.set(key, entry);
+            entriesByAtom.set(entry.atom, entry);
         }
         // Bound definitions as well as the registry's values. Mounted resources stay shared.
         if (resources.size > 512) {
@@ -90,26 +130,117 @@ function createQueryCache(runtime) {
         const config = queryDefinition(definition);
         protectSnapshot(args);
         const { entry, atom } = acquire(queryKey(definition, args), () => {
-            const effect = Effect.suspend(() => config.load(args));
+            const effect = Effect.suspend(() => config.load(args, previousValue(resources.get(queryKey(definition, args)))?.value));
             return runtime ? runtime.provide(effect) : effect;
         }, config.share);
         entry.query = definition;
+        entry.args = args;
+        entry.groups = config.groups;
+        entry.unused = config.unused ?? options.unused;
         return { entry, atom, config };
     };
+    const refresh = (entry) => {
+        entry.revision = ++nextRevision;
+        registry.refresh(entry.atom);
+    };
     const selectQuery = (definition, args) => {
         const { entry, atom, config } = acquireQuery(definition, args);
+        if (entry.canceled && !previousValue(entry))
+            refresh(entry);
         if (registry.getNodes().has(atom) &&
             entry.loadedAt !== undefined &&
             Date.now() - entry.loadedAt >= config.staleTime) {
             const current = registry.get(atom);
             if (!current.waiting)
-                registry.refresh(atom);
+                refresh(entry);
         }
         return atom;
     };
+    const retain = (atom) => {
+        const entry = entriesByAtom.get(atom);
+        if (!entry)
+            return () => { };
+        entry.users++;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            entry.users--;
+            if (!disposed &&
+                entry.users === 0 &&
+                entry.unused === 'cancel' &&
+                registry.getNodes().has(entry.atom) &&
+                registry.get(entry.atom).waiting)
+                registry.set(entry.atom, cancelValue);
+        };
+    };
+    const abortPrefetches = (entry) => {
+        // oxlint-disable-next-line unicorn/no-useless-spread -- Cancellation can add or remove observers reentrantly.
+        for (const abort of [...entry.prefetches])
+            abort();
+    };
     const cache = {
-        prefetch(definition, args) {
-            return Effect.suspend(() => AtomRegistry.getResult(registry, selectQuery(definition, args), { suspendOnWaiting: true }));
+        batch: Atom.batch,
+        getQueryData(definition, args) {
+            return previousValue(resources.get(queryKey(definition, args)))?.value;
+        },
+        invalidateWhere(definition, predicate) {
+            const selected = [...resources.values()].filter((entry) => entry.query === definition && predicate(entry.args));
+            Atom.batch(() => {
+                for (const entry of selected)
+                    refresh(entry);
+            });
+        },
+        invalidateGroup(group) {
+            Atom.batch(() => {
+                for (const entry of resources.values())
+                    if (entry.groups?.includes(group))
+                        refresh(entry);
+            });
+        },
+        cancelQuery(definition, ...selected) {
+            Atom.batch(() => {
+                for (const [key, entry] of resources)
+                    if (entry.query === definition &&
+                        (!selected.length || key === queryKey(definition, selected[0])))
+                        if (registry.getNodes().has(entry.atom) && registry.get(entry.atom).waiting) {
+                            abortPrefetches(entry);
+                            registry.set(entry.atom, cancelValue);
+                        }
+            });
+        },
+        removeQuery(definition, ...selected) {
+            Atom.batch(() => {
+                for (const [key, entry] of resources)
+                    if (entry.query === definition &&
+                        (!selected.length || key === queryKey(definition, selected[0])))
+                        if (registry.getNodes().has(entry.atom)) {
+                            abortPrefetches(entry);
+                            registry.set(entry.atom, removeValue);
+                        }
+            });
+        },
+        prefetch(definition, args, options) {
+            return Effect.suspend(() => {
+                checkWritable();
+                const atom = selectQuery(definition, args);
+                const release = retain(atom);
+                const entry = entriesByAtom.get(atom);
+                const signal = Deferred.makeUnsafe();
+                const abort = () => {
+                    Deferred.doneUnsafe(signal, Effect.interrupt);
+                };
+                entry.prefetches.add(abort);
+                return Effect.suspend(() => {
+                    if (options?.refresh && registry.getNodes().has(atom) && !registry.get(atom).waiting)
+                        refresh(entry);
+                    return Effect.raceFirst(Deferred.await(signal), AtomRegistry.getResult(registry, atom, { suspendOnWaiting: true }));
+                }).pipe(Effect.ensuring(Effect.sync(() => {
+                    entry.prefetches.delete(abort);
+                    release();
+                })));
+            });
         },
         setQueryData(definition, args, value) {
             checkWritable();
@@ -140,12 +271,10 @@ function createQueryCache(runtime) {
             if (selected.length) {
                 const entry = resources.get(queryKey(definition, selected[0]));
                 if (entry)
-                    registry.refresh(entry.atom);
+                    refresh(entry);
             }
             else {
-                for (const entry of resources.values())
-                    if (entry.query === definition)
-                        registry.refresh(entry.atom);
+                cache.invalidateWhere(definition, () => true);
             }
         },
         onReset(listener) {
@@ -155,21 +284,45 @@ function createQueryCache(runtime) {
         resetResources() {
             Atom.batch(() => {
                 for (const entry of resources.values()) {
+                    abortPrefetches(entry);
                     entry.load = () => Effect.interrupt;
-                    registry.refresh(entry.atom);
+                    refresh(entry);
                 }
                 resources.clear();
                 registry.update(generation, (value) => value + 1);
             });
         },
+        close() {
+            if (!closing) {
+                closing = Effect.suspend(() => {
+                    cache.dispose();
+                    return settlement.wait();
+                });
+            }
+            return closing;
+        },
         dispose() {
             if (disposed)
                 return;
             disposed = true;
+            for (const entry of resources.values())
+                abortPrefetches(entry);
             registry.dispose();
             resources.clear();
         },
     };
-    registerCache(cache, { registry, generation, query: selectQuery });
+    registerCache(cache, {
+        disposed: () => disposed,
+        refresh: (atom) => {
+            const entry = entriesByAtom.get(atom);
+            if (entry)
+                refresh(entry);
+        },
+        registry,
+        generation,
+        query: selectQuery,
+        retain,
+        revision: (definition, args) => resources.get(queryKey(definition, args))?.revision,
+    });
     return Object.freeze(cache);
 }

package/dist/collection.d.ts

@@ -9,7 +9,7 @@ export interface Rows<A> {
     slice(start?: number, end?: number): Rows<A>;
 }
 /** Validate without retaining values. Positions are zero-based array indices. */
-export declare function validateIdentities<A>(items: readonly A[], identity: (item: A, index: number) => Identity): Identity[];
+export declare function validateIdentities<A, K>(items: readonly A[], identity: (item: A, index: number) => K): K[];
 export interface Collection<A> {
     from(this: void, items: readonly (A | Snapshot<A>)[]): Rows<Snapshot<A>>;
     share<B extends A | Snapshot<A>>(this: void, previous: readonly B[], next: readonly B[]): readonly Snapshot<B>[];

package/dist/collection.js

@@ -2,10 +2,8 @@ import { shareData } from './sharing.js';
 /** Validate without retaining values. Positions are zero-based array indices. */
 export function validateIdentities(items, identity) {
     const seen = new Map();
-    return items.map((item, index) => {
+    return Array.from(items, (item, index) => {
         const key = identity(item, index);
-        if (typeof key !== 'string' && typeof key !== 'number')
-            throw new Error(`Invalid collection identity at index ${index}. Use a string or number domain identity, or sequence(items) for positional identity.`);
         const previous = seen.get(key);
         if (previous !== undefined)
             throw new Error(`Duplicate collection identity at indices ${previous} and ${index}. Identity must be unique within the collection; use a composite domain identity when IDs are only locally unique.`);

package/dist/component.d.ts

@@ -4,6 +4,7 @@ import type { Transition } from './program.js';
 import { type UiRuntime } from './runtime.js';
 /** Local fields with no command lifecycle. Sends are shallow patches, never updater callbacks. */
 export declare function localComponent<Props, State extends object>(definition: {
+    identity?: (props: Snapshot<Props>) => unknown;
     init: (props: Snapshot<Props>) => (State | Snapshot<State>) & {
         readonly props?: never;
     };
@@ -17,6 +18,7 @@ export declare function localComponent<Props, State extends object>(definition:
 export declare function component<Props, Model extends {
     readonly props: Props;
 }, Message, R = never>(definition: {
+    identity?: (props: Snapshot<Props>) => unknown;
     init: (props: Snapshot<Props>) => Model | Snapshot<Model>;
     receive?: (model: Snapshot<Model>, props: Snapshot<Props>) => Transition<Model, Message, R>;
     update: (model: Snapshot<Model>, message: Message) => Transition<Model, Message, R>;
@@ -28,6 +30,7 @@ export declare function component<Props, Model extends {
 })): View<Props, never>;
 /** Mount an existing program without introducing a second state owner. */
 export declare function programView<Props, Model, Message>(definition: {
+    identity?: (props: Snapshot<Props>) => unknown;
     create: (props: Snapshot<Props>) => import('./program').Program<Model, Message>;
     receive: (source: import('./program').Program<Model, Message>, props: Snapshot<Props>) => void;
     view: View<Model, Message>;