effectweb 0.2.3 → 0.3.1

package/README.md

@@ -6,4 +6,96 @@ Use with `@effectweb/compiler/vite` and Effect `4.0.0-rc.112`. The package inclu
 
 See [setup and example](https://github.com/DerpyCrabs/EffectWeb#vite-setup).
 
-Early API; runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.
+Runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.
+
+## Query identity and account ownership
+
+A query definition has its own identity. Within one cache, all request arguments form its key automatically:
+
+```ts
+const page = query({
+  name: 'message-page',
+  load: (args: { accountId: string; threadId: string; cursor?: string }) =>
+    api.messages(args.accountId, args.threadId, args.cursor),
+});
+```
+
+Request arguments use the same canonical encoding for cache lookup, prefetch, writes, invalidation, and `queryResource.select`. Object property order is ignored; array order matters. Strings, finite numbers, booleans, `null`, and explicit `undefined` are supported recursively in dense arrays and plain objects. Missing properties differ from properties containing `undefined`, and `0` differs from `-0`. Functions, symbols, bigint, nonfinite numbers, cycles, class instances, accessors, nonenumerable properties, sparse arrays, and arrays with extra properties throw `TypeError`. Repeated references to the same plain object are supported. Published argument objects are frozen and are not cloned.
+
+Pass every load-relevant value as an argument, including account, filters, pagination, locale, and permissions when they affect the result. Custom `key` projections are rejected. Provide service instances through the Effect environment instead of query arguments. Separate query definitions do not share entries even if their names and arguments match. `select(undefined)` disables selection; an explicit `undefined` inside an argument object remains part of its identity. A query without arguments uses `true` for selection and prefetch.
+
+Give authenticated data an account lifetime:
+
+```ts
+const account = modelOwner({ accountId }, { runtime });
+const cache = account.own(makeQueryCache(runtime));
+const messages = observeQuery(account, cache, page, (result) => {
+  // Publish the immutable result into application state.
+});
+messages.select({ accountId, threadId });
+
+// Sign out or switch account: dispose this lifetime, then create the next one.
+account.dispose();
+```
+
+Independent caches isolate account data even when services derive authentication from their environment. If an application deliberately reuses a cache across accounts, include account identity in every authenticated query key and call `cache.resetResources()` at the boundary before selecting the new account. Reset interrupts old resources and returns existing query observers to their initial state; select again to enter the new generation. Disposing only a query observer releases its subscription; it does not erase shared cached values. Own shared caches at the account or application scope, not in individual views.
+
+Use `cache.setQueryData(query, args, value)` to seed or replace a cached success, and `cache.updateQueryData(query, args, update)` to change an existing success. The updater receives readonly data; returning `undefined` skips the write. Both publish to current observers and supersede pending loads for those arguments. Use `setQueryData` to store a successful `undefined` value. Query definitions and cache registries are opaque; use the public cache and observation methods.
+
+## Write concurrency
+
+`modelOwner.run(slot, effect, policy)` and `defineTasks(owner, definitions)` support these policies:
+
+| Policy          | Behavior for an occupied slot                                           |
+| --------------- | ----------------------------------------------------------------------- |
+| `drop`          | Ignore the new request.                                                 |
+| `replace`       | Cancel active work and discard pending requests; start the new request. |
+| `parallel`      | Start the new request alongside active work.                            |
+| `queue`         | Append the request; run it after earlier work finishes.                 |
+| `latest-queued` | Keep active work; replace all pending requests with the newest request. |
+
+Every command requires an explicit `policy`. Create stable operation identities with `commandSlot('save')`; equal diagnostic names do not share a slot. Component `defineTasks(...).tasks(...)` and `taskComponent` support all except `parallel`, since their single result slot represents serial work. Command mapping and runtime service provisioning preserve the policy. Actions sharing a slot share concurrency and cancellation. A queued request waits for every active request in that slot if policies are mixed; keep a consistent policy per slot for predictable write behavior.
+
+Use `queue` when each accepted operation matters, such as appending messages. Use `latest-queued` when saving complete document snapshots and only the newest pending snapshot matters:
+
+```ts
+const writes = defineTasks(owner, {
+  save: { policy: 'latest-queued', run: (document: Snapshot<Document>) => storage.save(document) },
+});
+
+writes.save(owner.read().document);
+```
+
+Component tasks capture the model snapshot and input when `Run` is submitted, including requests that wait in a queue. Editing fields afterward does not replace that captured model. Controller tasks retain their supplied arguments; their factories execute when work starts. Pass `owner.read()` data as arguments to capture submission state, or read inside the Effect when execution-time state is intended. Effects and inputs are retained, not deep-cloned; keep supplied data immutable. Dropped and coalesced pending factories are never invoked.
+
+Queue progress continues after successes, typed failures, or defects. Component results remain `waiting` while more work is pending, publish each settlement, and retain the latest successful value if a later write fails. Action failures use the owner's error reporter. `cancel`, component reset or identity change, and disposal discard pending requests and interrupt active work; stale command completions cannot publish afterward. `awaitIdle` includes pending work. Cancellation cannot undo an external write that already completed. Transactions admit their whole command batch before starting Effects, so replacements and cancellation can remove superseded work without executing it.
+
+## Lazy views and portals
+
+`lazyView(() => fromPromise(() => import('./Reader').then((module) => module.Reader)))` loads a view when mounted. It accepts typed `pending` and `failure` views and a `runtime` when the loader requires services. Each unresolved placement owns its load; unmounting interrupts it. Successful definitions are cached for future mounts. Render a lazy view through `ViewBinding` with its current model and sender.
+
+`<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
+
+Mount a development panel before mounting the application so it sees initial evaluations:
+
+```ts
+import { mountBindingInspector } from 'effectweb/diagnostics';
+
+const removeInspector = mountBindingInspector(document.querySelector<HTMLElement>('#inspector')!);
+// Mount the application here. On teardown or HMR:
+// 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.
+
+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.
+
+## Immutable inputs and outputs
+
+Published `Snapshot<T>` values are recursively readonly, including nested arrays/tuples and async success data. View/slot composition, component inputs, owner patches, and task field updates accept readonly branches without casts. Query cache reads, subscriptions, and prefetch publish the same readonly data. Plain objects and arrays are frozen before publication in every build; snapshot protection cannot be disabled.
+
+Functions, Effects, DOM nodes, and explicitly marked service classes retain their own API. See the [authoring guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/authoring.md) for migration examples, `SnapshotOpaque`, state ownership, form composition, and reconciling async loads with live updates.

package/dist/AsyncContent.d.ts

@@ -13,8 +13,8 @@ export interface AsyncContentProps<A, E> {
 }
 type Props = AsyncContentProps<unknown, unknown>;
 /** Presentation only: resource owners choose identity, loading, caching and cancellation. */
-export declare const AsyncContent: {
-    <A, E>(props: AsyncContentProps<A, E>): JSX.Element;
+export declare const AsyncContent: JSX.ComponentType & {
+    <A, E>(this: never, props: AsyncContentProps<A, E>): JSX.Element;
     readonly build: View<Props, never>["build"];
 };
 export {};

package/dist/AsyncContent.js

@@ -1,9 +1,11 @@
 import * as _ew_dom from "./dom.js";
+import { commandSlot } from "./program.js";
 import { Cause, Effect, Option } from "effect";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import { component } from "./component.js";
 import { view } from "./index.js";
 import { effectCommand } from "./program.js";
+const commandPending = commandSlot("pending");
 const implementation = component({
     init: (props) => ({
         props,
@@ -19,7 +21,7 @@ const implementation = component({
                     pending: false,
                     visible: false
                 },
-                cancel: ["pending"]
+                cancel: [commandPending]
             };
         if (model.pending && model.props.pendingDelay === props.pendingDelay)
             return { model: {
@@ -33,8 +35,9 @@ const implementation = component({
                 pending: true,
                 visible: delay === 0
             },
-            cancel: ["pending"],
-            commands: delay === 0 ? [] : [effectCommand("pending", () => Effect.sleep(delay), {
+            cancel: [commandPending],
+            commands: delay === 0 ? [] : [effectCommand(commandPending, () => Effect.sleep(delay), {
+                    policy: "replace",
                     onSuccess: () => ({ type: "ShowPending" }),
                     onFailure: () => ({ type: "ShowPending" })
                 })]
@@ -47,7 +50,7 @@ const implementation = component({
     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;
+            return _ew_dom.intrinsic(_ew_dom.intrinsic(_ew_capture_6, ["props", "content"], "@slot"), ["props", "failure"], "@slot").props;
         });
         const _ew_derived_7 = _ew_scope_1.derive(() => [_ew_derived_4()?.result], () => {
             const _ew_capture_9 = _ew_derived_4();

package/dist/actions.d.ts

@@ -1,5 +1,6 @@
 import type { Send, Transition } from './program.js';
-type Handler<Model> = (model: Model, ...args: never[]) => Transition<Model, unknown>;
+import type { Snapshot } from './snapshot.js';
+type Handler<Model, R> = (model: Snapshot<Model>, ...args: never[]) => Transition<Model, unknown, R>;
 type Arguments<F> = F extends (model: never, ...args: infer Args) => unknown ? Args : never;
 type HandlerMessage<Handlers> = {
     [Name in keyof Handlers]: {
@@ -18,9 +19,9 @@ type Creators<Handlers> = {
 type Dispatch<Handlers> = {
     [Name in keyof Handlers]: (...args: Arguments<Handlers[Name]>) => void;
 };
-export declare function defineActions<Model>(): <Handlers extends Record<string, Handler<Model>>>(handlers: Handlers) => {
+export declare function defineActions<Model, R = never>(): <Handlers extends Record<string, Handler<Model, R>>>(handlers: Handlers) => {
     message: Creators<Handlers>;
     bind(this: void, send: Send<HandlerMessage<Handlers>>): Dispatch<Handlers>;
-    update(this: void, model: Model, action: HandlerMessage<Handlers>): ReturnType<Handlers[keyof Handlers]>;
+    update(this: void, model: Snapshot<Model>, action: HandlerMessage<Handlers>): ReturnType<Handlers[keyof Handlers]>;
 };
 export {};

package/dist/actions.js

@@ -23,6 +23,7 @@ export function defineActions() {
                 if (!Object.hasOwn(handlers, action.type))
                     throw new Error(`Unknown action: ${String(action.type)}`);
                 const handler = handlers[action.type];
+                // oxlint-disable-next-line typescript/no-unsafe-return -- The indexed handler and ReturnType refer to the same validated generic member.
                 return handler(model, ...action.args);
             },
         };

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

@@ -0,0 +1,18 @@
+import type * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import type * as Atom from 'effect/unstable/reactivity/Atom';
+import type * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
+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>>;
+}
+export declare function registerCache<R>(cache: QueryCache<R>, internals: CacheInternals<R>): void;
+/** Private implementation access; deliberately absent from package exports. */
+export declare function cacheInternals<R>(cache: QueryCache<R>): CacheInternals<R>;

package/dist/cache-internals.js

@@ -0,0 +1,11 @@
+const caches = new WeakMap();
+export function registerCache(cache, internals) {
+    caches.set(cache, internals);
+}
+/** Private implementation access; deliberately absent from package exports. */
+export function cacheInternals(cache) {
+    const internals = caches.get(cache);
+    if (!internals)
+        throw new TypeError('Use makeQueryCache() to create a cache.');
+    return internals;
+}

package/dist/cache.d.ts

@@ -1,22 +1,41 @@
+import { type Snapshot } from './snapshot.js';
 import { Effect } from 'effect';
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
-import * as Atom from 'effect/unstable/reactivity/Atom';
-import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
-import type { Query } from './query.js';
+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>;
-declare function createQueryCache<R>(runtime?: UiRuntime<R>): {
-    registry: AtomRegistry.AtomRegistry;
-    generation: Atom.Writable<number, number>;
-    resource<A, E = unknown>(key: string, load: () => Effect.Effect<A, E>): Atom.Atom<AsyncResult.AsyncResult<A, E>>;
-    query: <Args, A, E>(definition: Query<Args, A, E, R>, args: Args) => Atom.Atom<AsyncResult.AsyncResult<A, E>>;
-    prefetch<Args, A, E>(definition: Query<Args, A, E, R>, args: Args): Effect.Effect<A, E>;
-    invalidateQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [Args]): void;
-    invalidate(prefix: string): void;
+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> {
+    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>;
+    /**
+     * Update an existing success, including one retained during refresh or failure, and supersede its load.
+     * No success or an undefined updater return skips the write. Use setQueryData to seed or store undefined.
+     * Updaters run synchronously on readonly data; a throw leaves the cached value unchanged.
+     */
+    updateQueryData<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>, update: (previous: Snapshot<A>) => NoInfer<A> | Snapshot<NoInfer<A>> | undefined): Snapshot<A> | undefined;
+    invalidateQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [NoInfer<Args> | Snapshot<NoInfer<Args>>]): void;
+    /** 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(): Promise<void>;
     dispose(): void;
-};
-export type QueryCache<R = never> = ReturnType<typeof createQueryCache<R>>;
+}