effectweb 0.2.3 → 0.3.1

package/dist/keyed-tasks.js

@@ -0,0 +1,97 @@
+import { Cause, Effect, Exit } from 'effect';
+import { commandSlot, program } from './program.js';
+import { defaultUiRuntime } from './runtime.js';
+import { reportError, reportSafely } from './errors.js';
+import { protectSnapshot } from './snapshot.js';
+/** Per-entity serialization. Inputs are captured now; run reads services when work starts. */
+export function keyedTasks(owner, definition, ...provided) {
+    const runtime = provided[0] ?? defaultUiRuntime;
+    const entries = new Map();
+    let disposed = false;
+    const slot = commandSlot(definition.name);
+    const makeSource = () => program({
+        initial: null,
+        update: (model, message) => 'command' in message ? { model, commands: [message.command] } : { model, cancel: [slot] },
+    });
+    // Each key owns a program, including its interrupted fibers, so drain never waits on other keys.
+    const get = (key) => {
+        let entry = entries.get(key);
+        if (!entry) {
+            entry = { source: makeSource(), version: 0, retiring: false };
+            entries.set(key, entry);
+        }
+        return entry;
+    };
+    const dispose = () => {
+        disposed = true;
+        for (const entry of entries.values())
+            entry.source.dispose();
+    };
+    const close = async () => {
+        dispose();
+        await Promise.all([...entries.values()].map((entry) => entry.source.close()));
+        entries.clear();
+    };
+    owner.own({ dispose, close });
+    return {
+        submit(key, input) {
+            if (disposed || owner.disposed)
+                return { outcome: Promise.resolve(Object.freeze({ _tag: 'Cancelled' })) };
+            const captured = protectSnapshot(input);
+            const entry = get(key);
+            entry.version++;
+            let settle;
+            const outcome = new Promise((resolve) => {
+                settle = (result) => resolve(protectSnapshot(result));
+            });
+            outcome
+                .then(async () => {
+                if (entry.retiring)
+                    return;
+                entry.retiring = true;
+                let version;
+                do {
+                    version = entry.version;
+                    await entry.source.awaitStopped();
+                } while (version !== entry.version);
+                if (entries.get(key) === entry) {
+                    entries.delete(key);
+                    entry.source.dispose();
+                }
+            })
+                .catch((error) => reportSafely(reportError, error));
+            const action = Effect.uninterruptibleMask((restore) => restore(Effect.suspend(() => definition.run(key, captured)).pipe(Effect.map((value) => protectSnapshot(value)))).pipe(Effect.exit, Effect.flatMap((exit) => Effect.sync(() => settle(Exit.isSuccess(exit)
+                ? { _tag: 'Success', value: exit.value }
+                : Cause.hasInterruptsOnly(exit.cause)
+                    ? { _tag: 'Cancelled' }
+                    : { _tag: 'Failure', cause: exit.cause })))));
+            entry.source.send({
+                command: {
+                    slot,
+                    policy: definition.policy,
+                    action: runtime.provide(action),
+                    onDiscard: (_tag) => settle({ _tag }),
+                },
+            });
+            return { outcome };
+        },
+        cancel(key) {
+            const entry = entries.get(key);
+            if (entry) {
+                entry.version++;
+                entry.source.send({ cancel: true });
+            }
+        },
+        async drain(...selected) {
+            const pending = selected.length
+                ? [entries.get(selected[0])].filter((entry) => !!entry)
+                : [...entries.values()];
+            await Promise.all(pending.map(async (entry) => {
+                await entry.source.awaitIdle();
+                await entry.source.awaitStopped();
+            }));
+        },
+        close,
+        dispose,
+    };
+}

package/dist/lazy.d.ts

@@ -0,0 +1,23 @@
+import { Effect, type Cause } from 'effect';
+import { type View } from './dom.js';
+import { type UiRuntime } from './runtime.js';
+export interface LazyViewOptions<Model, Message, E> {
+    readonly pending?: View<Model, Message>;
+    readonly failure?: View<{
+        readonly model: Model;
+        readonly cause: Cause.Cause<E>;
+    }, Message>;
+}
+/**
+ * Mount-owned loading with current inputs and a reusable successful definition.
+ * Unresolved placements own independent requests; unmount interrupts their work.
+ */
+export declare function lazyView<Model, Message = never, E = never, R = never>(load: () => Effect.Effect<View<Model, Message>, E, R>, ...provided: [R] extends [never] ? [
+    options?: LazyViewOptions<NoInfer<Model>, NoInfer<Message>, NoInfer<E>> & {
+        readonly runtime?: UiRuntime<R>;
+    }
+] : [
+    options: LazyViewOptions<NoInfer<Model>, NoInfer<Message>, NoInfer<E>> & {
+        readonly runtime: UiRuntime<R>;
+    }
+]): View<Model, Message>;

package/dist/lazy.js

@@ -0,0 +1,66 @@
+import { Effect, Fiber } from 'effect';
+import { child, compiled, viewRegion } from './dom.js';
+import { reportSafely } from './errors.js';
+import { defaultUiRuntime } from './runtime.js';
+/**
+ * Mount-owned loading with current inputs and a reusable successful definition.
+ * Unresolved placements own independent requests; unmount interrupts their work.
+ */
+export function lazyView(load, ...provided) {
+    const options = provided[0];
+    const runtime = options?.runtime ?? defaultUiRuntime;
+    let loaded;
+    return compiled((scope, parent, before) => {
+        const render = viewRegion(scope, parent, before);
+        if (loaded) {
+            render(loaded);
+            return;
+        }
+        render(options?.pending);
+        let fiber;
+        const interrupt = () => {
+            if (fiber)
+                Effect.runFork(Fiber.interrupt(fiber));
+        };
+        scope.cleanups.push(interrupt);
+        if (scope.disposed)
+            return;
+        const finished = scope.settlement.begin();
+        try {
+            fiber = Effect.runFork(runtime.provide(Effect.suspend(load)));
+            fiber.addObserver(finished);
+        }
+        catch (error) {
+            finished();
+            throw error;
+        }
+        if (scope.disposed) {
+            interrupt();
+            return;
+        }
+        fiber.addObserver((exit) => {
+            if (scope.disposed)
+                return;
+            try {
+                if (exit._tag === 'Success') {
+                    loaded = exit.value;
+                    render(loaded);
+                }
+                else {
+                    const failure = options?.failure;
+                    if (failure)
+                        render(compiled((scope, parent, before) => {
+                            child(scope, parent, before, failure, () => [scope.value], () => ({ model: scope.value, cause: exit.cause }), scope.send);
+                        }));
+                    else {
+                        render(undefined);
+                        reportSafely(scope.report, exit.cause);
+                    }
+                }
+            }
+            catch (error) {
+                reportSafely(scope.report, error);
+            }
+        });
+    });
+}

package/dist/load.d.ts

@@ -4,9 +4,9 @@ export declare const loadEffect: <A, E, R>(load: () => UiLoad<A, E, R>) => UiLoa
 /** Adapt Promise libraries at the integration boundary. Pass the signal to APIs that support it. */
 export declare const fromPromise: <A>(load: (signal: AbortSignal) => PromiseLike<A>) => UiLoad<A>;
 export interface UiPage<A, Cursor> {
-    items: A[];
-    totalCount?: number;
-    next: Cursor | undefined;
+    readonly items: readonly A[];
+    readonly totalCount?: number;
+    readonly next: Cursor | undefined;
 }
 /** Read a local cache when executed, then acquire missing data through the same Effect contract. */
 export declare function cachedLoad<A, E, R>(read: () => A | undefined, load: () => UiLoad<A, E, R>): UiLoad<A, E, R>;

package/dist/mount.d.ts

@@ -1,25 +1,24 @@
+import type { Snapshot } from './snapshot.js';
 import { type ReportError } from './errors.js';
 import { Effect } from 'effect';
 import { type UiRuntime } from './runtime.js';
-import type { JSX } from './jsx.js';
+export { Portal, type PortalProps } from './dom.js';
 type Work<R = never> = (() => void) | {
     dispose: () => void;
     update?: () => void;
 } | Effect.Effect<never, unknown, R>;
-export declare function Portal(_props: {
-    children?: JSX.Element;
-}): JSX.Element;
-export interface DomMount {
+export interface DomMount<T extends Element = Element> {
     readonly identity: unknown;
     readonly data: unknown;
-    readonly acquire: (element: Element, input: () => unknown) => Work;
+    readonly acquire: (element: T, input: () => unknown) => Work;
 }
 /** Element-owned work. Changed acquisition functions replace and interrupt the prior lifetime. */
-export declare function domMount<T extends Element, R = never>(start: (element: T) => Work<R>, ...provided: [R] extends [never] ? [runtime?: UiRuntime<R>] : [runtime: UiRuntime<R>]): DomMount;
+export declare function domMount<T extends Element, R = never>(start: (element: T) => Work<R>, ...provided: [R] extends [never] ? [runtime?: UiRuntime<R>] : [runtime: UiRuntime<R>]): DomMount<T>;
 /** A stable DOM lifecycle with fresh immutable inputs, for focus, measurements and native events. */
-export declare function domBinding<T extends Element, A, R = never>(data: A, acquire: (element: T, input: () => A) => Work<R>, ...provided: [R] extends [never] ? [runtime?: UiRuntime<R>] : [runtime: UiRuntime<R>]): DomMount;
-export declare function startMount(element: Element, mount: DomMount, report?: ReportError): {
-    update(next: DomMount): boolean;
-    dispose(): void;
+export declare function domBinding<T extends Element, A, R = never>(data: A | Snapshot<A>, acquire: (element: T, input: () => Snapshot<A>) => Work<R>, ...provided: [R] extends [never] ? [runtime?: UiRuntime<R>] : [runtime: UiRuntime<R>]): DomMount<T>;
+export declare function startMount<T extends Element>(element: T, mount: DomMount<T>, report?: ReportError): {
+    closed: Promise<void>;
+    close(): Promise<void>;
+    update(next: DomMount<T>): boolean;
+    dispose: () => void;
 };
-export {};

package/dist/mount.js

@@ -1,9 +1,7 @@
 import { reportError, reportSafely } from './errors.js';
 import { Effect, Fiber } from 'effect';
 import { defaultUiRuntime } from './runtime.js';
-export function Portal(_props) {
-    throw new Error('Portal must be compiled inside a view');
-}
+export { Portal } from './dom.js';
 /** Element-owned work. Changed acquisition functions replace and interrupt the prior lifetime. */
 export function domMount(start, ...provided) {
     const runtime = provided[0] ?? defaultUiRuntime;
@@ -33,11 +31,39 @@ export function startMount(element, mount, report = reportError) {
     const work = mount.acquire(element, () => data);
     const fiber = Effect.isEffect(work) ? Effect.runFork(work) : undefined;
     let disposed = false;
+    let finish;
+    const closed = new Promise((resolve) => {
+        finish = resolve;
+    });
     fiber?.addObserver((exit) => {
         if (exit._tag === 'Failure' && !disposed)
             reportSafely(report, exit.cause);
+        finish();
     });
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        if (fiber)
+            Effect.runFork(Fiber.interrupt(fiber));
+        else {
+            try {
+                if (typeof work === 'function')
+                    work();
+                else if ('dispose' in work)
+                    work.dispose();
+            }
+            finally {
+                finish();
+            }
+        }
+    };
     return {
+        closed,
+        close() {
+            dispose();
+            return closed;
+        },
         update(next) {
             if (next.identity !== mount.identity)
                 return false;
@@ -46,16 +72,6 @@ export function startMount(element, mount, report = reportError) {
                 work.update?.();
             return true;
         },
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            if (fiber)
-                Effect.runFork(Fiber.interrupt(fiber));
-            else if (typeof work === 'function')
-                work();
-            else if ('dispose' in work)
-                work.dispose();
-        },
+        dispose,
     };
 }

package/dist/owner.d.ts

@@ -1,9 +1,9 @@
 import { type Snapshot } from './snapshot.js';
 import { Effect } from 'effect';
-import { type Program } from './program.js';
+import { type Program, type TaskPolicy, type CommandSlot } from './program.js';
 import { type ReportError } from './errors.js';
 import type { UiRuntime } from './runtime.js';
-export type TaskPolicy = 'replace' | 'drop' | 'parallel';
+export type { TaskPolicy } from './program.js';
 export interface DisposableOwner {
     readonly disposed: boolean;
     readonly own: <A extends {
@@ -13,18 +13,23 @@ export interface DisposableOwner {
 export interface ModelOwner<Model extends object, R = never> extends DisposableOwner {
     readonly source: Program<Model, never>;
     readonly read: () => Snapshot<Model>;
-    readonly patch: (changes: Partial<Model>) => void;
-    readonly edit: <K extends keyof Model>(key: K, change: (value: Snapshot<Model[K]>) => Snapshot<Model[K]>) => void;
+    /** Expose only controller-selected editable fields to a view. */
+    readonly fields: <const Keys extends readonly (keyof Model)[]>(...keys: Keys) => {
+        readonly [K in Keys[number]]: (value: Model[K] | Snapshot<Model[K]>) => void;
+    };
+    readonly patch: (changes: Partial<Model> | Partial<Snapshot<Model>>) => void;
+    readonly edit: <K extends keyof Model>(key: K, change: (value: Snapshot<Model[K]>) => Model[K] | Snapshot<Model[K]>) => void;
     /** Synchronous transaction. Reads see staged changes; a throw discards changes and work. */
     readonly transaction: <A>(work: () => A & (A extends PromiseLike<unknown> ? never : unknown)) => A;
-    readonly run: (slot: string, effect: Effect.Effect<unknown, unknown, R>, policy?: TaskPolicy) => void;
-    readonly cancel: (slot: string) => void;
-    readonly isRunning: (slot: string) => boolean;
-    readonly awaitIdle: () => Promise<void>;
+    readonly run: (slot: CommandSlot, effect: Effect.Effect<unknown, unknown, R>, policy: TaskPolicy) => void;
+    readonly cancel: (slot: CommandSlot) => void;
+    readonly isRunning: (slot: CommandSlot) => boolean;
+    readonly awaitIdle: (slot?: CommandSlot) => Promise<void>;
+    /** Interrupt and join work before closing owned dependencies in reverse order. */
+    readonly close: () => Promise<void>;
     readonly dispose: () => void;
 }
 type Options = {
-    checkSnapshots?: boolean;
     name?: string;
     onDefect?: ReportError;
 };
@@ -32,4 +37,3 @@ export declare function modelOwner<Model extends object>(initial: Model, options
 export declare function modelOwner<Model extends object, R>(initial: Model, options: Options & {
     runtime: UiRuntime<R>;
 }): ModelOwner<Model, R>;
-export {};

package/dist/owner.js

@@ -1,62 +1,45 @@
-import { protectSnapshot, checkSnapshotsByDefault } from './snapshot.js';
+import { protectSnapshot } from './snapshot.js';
 import { Effect } from 'effect';
-import { program } from './program.js';
+import { program, } from './program.js';
 import { patchModel } from './state.js';
 import { runAll, reportError } from './errors.js';
 export function modelOwner(initial, options = {}) {
-    let disposed = false, nextTask = 0;
+    let disposed = false;
     let staged;
-    const groups = new Map();
     const cleanups = [];
+    let closing;
     const source = program({
         initial,
         ...options,
-        update(model, operations) {
+        update(snapshot, operations) {
+            let model = snapshot;
             const single = operations.length === 1 ? operations[0] : undefined;
             if (single?.type === 'Patch')
                 return { model: patchModel(model, single.changes) };
-            const commands = new Map();
+            const commands = [];
             const cancel = new Set();
-            const stop = (slot) => {
-                for (const key of groups.get(slot) ?? []) {
-                    cancel.add(key);
-                    commands.delete(key);
-                }
-                groups.delete(slot);
-            };
             for (const operation of operations) {
                 if (operation.type === 'Patch')
                     model = patchModel(model, operation.changes);
-                else if (operation.type === 'Cancel')
-                    stop(operation.slot);
+                else if (operation.type === 'Cancel') {
+                    cancel.add(operation.slot);
+                    for (let index = commands.length - 1; index >= 0; index--)
+                        if (commands[index].slot === operation.slot)
+                            commands.splice(index, 1);
+                }
                 else {
                     const { slot, effect, policy } = operation;
-                    if (policy === 'drop' && groups.has(slot))
-                        continue;
-                    if (policy === 'replace')
-                        stop(slot);
-                    const key = `${slot}:${++nextTask}`;
-                    const group = groups.get(slot) ?? new Set();
-                    groups.set(slot, group);
-                    group.add(key);
-                    commands.set(key, {
-                        slot: key,
-                        action: Effect.asVoid(effect).pipe(Effect.ensuring(Effect.sync(() => {
-                            group.delete(key);
-                            if (!group.size && groups.get(slot) === group)
-                                groups.delete(slot);
-                        }))),
-                    });
+                    commands.push({ slot, policy, action: Effect.asVoid(effect) });
                 }
             }
             return {
                 model,
                 cancel: [...cancel],
-                commands: [...commands.values()].map((command) => options.runtime ? options.runtime.command(command) : command),
+                commands: commands.map((command) => options.runtime ? options.runtime.command(command) : command),
             };
         },
     });
-    const read = () => protectSnapshot(staged?.model ?? source.model(), options.checkSnapshots ?? checkSnapshotsByDefault);
+    const read = () => protectSnapshot(staged?.model ?? source.model());
     const submit = (operation) => {
         if (disposed)
             return;
@@ -74,13 +57,56 @@ export function modelOwner(initial, options = {}) {
             return;
         disposed = true;
         source.dispose();
-        groups.clear();
-        runAll(cleanups.splice(0).reverse(), options.onDefect ?? reportError);
+        runAll(cleanups
+            .splice(0)
+            .reverse()
+            .map((resource) => () => resource.dispose()), options.onDefect ?? reportError);
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        disposed = true;
+        const resources = cleanups.splice(0).reverse();
+        let finish;
+        let fail;
+        closing = new Promise((resolve, reject) => {
+            finish = resolve;
+            fail = reject;
+        });
+        const closeResources = async () => {
+            await source.close();
+            const errors = [];
+            for (const resource of resources) {
+                try {
+                    if (resource.close)
+                        await resource.close();
+                    else
+                        resource.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length)
+                throw new AggregateError(errors, 'Owner cleanup failed.');
+        };
+        closeResources().then(finish, fail);
+        return closing;
     };
     return {
-        source: { model: source.model, send: source.send, subscribe: source.subscribe, dispose },
+        source: { model: source.model, send: source.send, subscribe: source.subscribe, dispose, close },
         read,
         patch,
+        fields: (...keys) => {
+            const controls = Object.create(null);
+            for (const key of keys) {
+                Object.defineProperty(controls, key, {
+                    enumerable: true,
+                    value: (value) => patch({ [key]: value }),
+                });
+            }
+            return Object.freeze(controls);
+        },
         edit: (key, change) => {
             if (!disposed) {
                 const changes = {};
@@ -116,18 +142,19 @@ export function modelOwner(initial, options = {}) {
                 staged = parent;
             }
         },
-        run: (slot, effect, policy = 'replace') => submit({ type: 'Run', slot, effect, policy }),
+        run: (slot, effect, policy) => submit({ type: 'Run', slot, effect, policy }),
         cancel: (slot) => submit({ type: 'Cancel', slot }),
-        isRunning: (slot) => groups.has(slot),
+        isRunning: (slot) => source.activeSlots().includes(slot),
         awaitIdle: source.awaitIdle,
         get disposed() {
             return disposed;
         },
+        close,
         own(resource) {
             if (disposed)
                 resource.dispose();
             else
-                cleanups.push(() => resource.dispose());
+                cleanups.push(resource);
             return resource;
         },
         dispose,

package/dist/pages.d.ts

@@ -1,49 +1,51 @@
+import type { Snapshot } from './snapshot.js';
 import { Cause } from 'effect';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import type { UiLoad, UiPage } from './load.js';
-import { type Transition, type Send } from './program.js';
-export interface PagesModel<Props, A, Cursor> {
+import { type Transition, type RunningProgram } from './program.js';
+import { type UiRuntime } from './runtime.js';
+export interface PagesModel<Props, A, Cursor, E = unknown> {
     readonly props: Props;
     readonly key: string | undefined;
-    readonly result: AsyncResult.AsyncResult<UiPage<A, Cursor>, unknown>;
+    readonly result: AsyncResult.AsyncResult<UiPage<A, Cursor>, E>;
     readonly append: boolean;
 }
-export type PagesMessage<A, Cursor> = {
+export type PagesRequest = {
     type: 'More';
 } | {
     type: 'Retry';
 } | {
     type: 'Refresh';
-} | {
+};
+/** Low-level reducer protocol, including completions for explicit program composition. */
+export type PagesMessage<A, Cursor, E = unknown> = PagesRequest | {
     type: 'Loaded';
     page: UiPage<A, Cursor>;
     append: boolean;
 } | {
     type: 'Failed';
-    cause: Cause.Cause<unknown>;
+    cause: Cause.Cause<E>;
 };
+/** An owned pagination source with immutable input updates. */
+export interface PagesProgram<Props, A, Cursor, E = unknown> extends RunningProgram<PagesModel<Props, A, Cursor, E>, PagesRequest> {
+    readonly receive: (props: Props | Snapshot<Props>) => void;
+}
+/** Reusable pagination transitions, or an independently owned source through create. */
+export interface Pagination<Props, A, Cursor, E = unknown> {
+    readonly init: (props: Props | Snapshot<Props>) => PagesModel<Props, A, Cursor, E> | Snapshot<PagesModel<Props, A, Cursor, E>>;
+    readonly receive: (model: PagesModel<Props, A, Cursor, E> | Snapshot<PagesModel<Props, A, Cursor, E>>, props: Props | Snapshot<Props>, options?: {
+        refresh?: boolean;
+    }) => Transition<PagesModel<Props, A, Cursor, E>, PagesMessage<A, Cursor, E>>;
+    readonly update: (model: PagesModel<Props, A, Cursor, E> | Snapshot<PagesModel<Props, A, Cursor, E>>, message: PagesMessage<A, Cursor, E>) => Transition<PagesModel<Props, A, Cursor, E>, PagesMessage<A, Cursor, E>>;
+    readonly create: (props: Props | Snapshot<Props>) => PagesProgram<Props, A, Cursor, E>;
+}
 /**
  * Pagination owns the `page` command slot. Key changes clear results and replace the request;
  * same-key refreshes keep the last success, and retries repeat the failed cursor.
  * Feed request inputs through receive; pass { refresh: true } for explicit same-key submissions.
  */
-export declare function pages<Props, A, Cursor>(definition: {
-    key: (props: Props) => string | undefined;
-    load: (props: Props, cursor: Cursor | undefined) => UiLoad<UiPage<A, Cursor>>;
-    itemKey: (item: A) => string;
-}): {
-    create(props: Props): {
-        send: Send<PagesMessage<A, Cursor>>;
-        receive: (props: Props) => void;
-        activeSlots: () => readonly string[];
-        awaitIdle: (slot?: string) => Promise<void>;
-        model: () => Readonly<PagesModel<Props, A, Cursor>>;
-        subscribe: (listener: (model: Readonly<PagesModel<Props, A, Cursor>>) => void) => () => void;
-        dispose: () => void;
-    };
-    init: (props: Props) => PagesModel<Props, A, Cursor>;
-    receive(model: PagesModel<Props, A, Cursor>, props: Props, options?: {
-        refresh?: boolean;
-    }): Transition<PagesModel<Props, A, Cursor>, PagesMessage<A, Cursor>>;
-    update(model: PagesModel<Props, A, Cursor>, message: PagesMessage<A, Cursor>): Transition<PagesModel<Props, A, Cursor>, PagesMessage<A, Cursor>>;
-};
+export declare function pages<Props, A, Cursor, E = unknown, R = never>(definition: {
+    key: (props: Snapshot<Props>) => string | undefined;
+    load: (props: Snapshot<Props>, cursor: Snapshot<Cursor> | undefined) => UiLoad<UiPage<A, Cursor>, E, R>;
+    itemKey: (item: Snapshot<A>) => string;
+}, ...provided: [R] extends [never] ? [runtime?: UiRuntime<R>] : [runtime: UiRuntime<R>]): Pagination<Props, A, Cursor, E>;