effectweb 0.1.0

package/dist/query.d.ts

@@ -0,0 +1,22 @@
+import type { Effect } from 'effect';
+/** One logical read. Share its definition between consumers, prefetching and mutations. */
+export interface Query<Args, A, E = never, R = never> {
+    readonly id: number;
+    readonly name: string;
+    readonly key: (args: Args) => string;
+    readonly load: (args: Args) => Effect.Effect<A, E, R>;
+    /** Revalidate on activation/prefetch after this many milliseconds. No polling timer. */
+    readonly staleTime: number;
+}
+/** Identity belongs to arguments, never callback identity. Each application cache owns account isolation. */
+export declare function query<A, E = never, R = never>(definition: {
+    readonly name: string;
+    readonly load: () => Effect.Effect<A, E, R>;
+    readonly staleTime?: number;
+}): Query<true, A, E, R>;
+export declare function query<Args, A, E = never, R = never>(definition: {
+    readonly name: string;
+    readonly key: (args: Args) => string;
+    readonly load: (args: Args) => Effect.Effect<A, E, R>;
+    readonly staleTime?: number;
+}): Query<Args, A, E, R>;

package/dist/query.js

@@ -0,0 +1,12 @@
+let nextQueryId = 0;
+export function query(definition) {
+    const staleTime = definition.staleTime ?? Infinity;
+    if (Number.isNaN(staleTime) || staleTime < 0)
+        throw new RangeError('Query staleTime must be nonnegative.');
+    return Object.freeze({
+        ...definition,
+        key: definition.key ?? (() => ''),
+        id: ++nextQueryId,
+        staleTime,
+    });
+}

package/dist/resource.d.ts

@@ -0,0 +1,34 @@
+import { Cause } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import type { UiLoad } from './load.js';
+import { type UiRuntime } from './runtime.js';
+import type { View } from './dom.js';
+export interface ResourceModel<Props, A, E = unknown> {
+    readonly props: Props;
+    readonly key: string | undefined;
+    readonly result: AsyncResult.AsyncResult<A, E>;
+}
+export type ResourceMessage<A, E = unknown> = {
+    type: 'Retry';
+} | {
+    type: 'Loaded';
+    value: A;
+} | {
+    type: 'Failed';
+    cause: Cause.Cause<E>;
+};
+export declare const available: <A>(result: AsyncResult.AsyncResult<A, unknown>) => A | undefined;
+export declare const resourceError: (result: AsyncResult.AsyncResult<unknown, unknown>) => string;
+/** A replaceable request owns one result. Key changes clear it; refreshes preserve the last success. */
+export declare function resourceComponent<Props, A, E = unknown, R = never>(definition: {
+    request: (props: Props) => {
+        key: string;
+        load: () => UiLoad<A, E, R>;
+        delay?: number;
+    } | undefined;
+    view: View<ResourceModel<Props, A, E>, ResourceMessage<A, E>>;
+} & ([R] extends [never] ? {
+    runtime?: UiRuntime<R>;
+} : {
+    runtime: UiRuntime<R>;
+})): View<Props, never>;

package/dist/resource.js

@@ -0,0 +1,59 @@
+import { Cause, Effect, Option } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import { loadEffect } from './load.js';
+import { component } from './component.js';
+import { defaultUiRuntime } from './runtime.js';
+import { effectCommand } from './program.js';
+export const available = (result) => Option.getOrUndefined(AsyncResult.value(result));
+export const resourceError = (result) => AsyncResult.isFailure(result) ? String(Cause.squash(result.cause)) : '';
+/** A replaceable request owns one result. Key changes clear it; refreshes preserve the last success. */
+export function resourceComponent(definition) {
+    const runtime = definition.runtime ?? defaultUiRuntime;
+    const request = (model, retry = false) => {
+        const selected = definition.request(model.props);
+        if (!retry && selected?.key === model.key)
+            return { model };
+        if (!selected)
+            return {
+                model: { ...model, key: undefined, result: AsyncResult.initial() },
+                cancel: ['load'],
+            };
+        return {
+            model: {
+                ...model,
+                key: selected.key,
+                result: AsyncResult.waiting(selected.key === model.key ? model.result : AsyncResult.initial()),
+            },
+            commands: [
+                effectCommand('load', () => runtime.provide(selected.delay
+                    ? Effect.sleep(selected.delay).pipe(Effect.andThen(loadEffect(selected.load)))
+                    : loadEffect(selected.load)), {
+                    onSuccess: (value) => ({ type: 'Loaded', value }),
+                    onFailure: (cause) => ({ type: 'Failed', cause }),
+                }),
+            ],
+        };
+    };
+    return component({
+        init: (props) => ({ props, key: undefined, result: AsyncResult.initial() }),
+        receive: (model, props) => request({ ...model, props }),
+        update: (model, message) => {
+            switch (message.type) {
+                case 'Retry':
+                    return request(model, true);
+                case 'Loaded':
+                    return { model: { ...model, result: AsyncResult.success(message.value) } };
+                case 'Failed':
+                    return {
+                        model: {
+                            ...model,
+                            result: AsyncResult.failureWithPrevious(message.cause, {
+                                previous: Option.some(model.result),
+                            }),
+                        },
+                    };
+            }
+        },
+        view: definition.view,
+    });
+}

package/dist/runtime.d.ts

@@ -0,0 +1,16 @@
+import { Context, Effect } from 'effect';
+import { type Command, type RunningProgram, type Transition } from './program.js';
+/** A binding to application-owned services, not a new scope or service lifetime. */
+export interface UiRuntime<R> {
+    readonly context: Context.Context<R>;
+    readonly provide: <A, E>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E>;
+    readonly command: <M>(command: Command<M, R>) => Command<M>;
+    readonly program: <M, Msg>(options: {
+        initial: M;
+        update: (model: M, message: Msg) => Transition<M, Msg, R>;
+        name?: string;
+        onDefect?: (cause: unknown) => void;
+    }) => RunningProgram<M, Msg>;
+}
+export declare function uiRuntime<R>(context: Context.Context<R>): UiRuntime<R>;
+export declare const defaultUiRuntime: UiRuntime<never>;

package/dist/runtime.js

@@ -0,0 +1,27 @@
+import { Context, Effect, Stream } from 'effect';
+import { program } from './program.js';
+export function uiRuntime(context) {
+    const provide = (effect) => Effect.provideContext(effect, context);
+    const command = (value) => value.stream
+        ? { slot: value.slot, stream: value.stream.pipe(Stream.provideContext(context)) }
+        : value.action
+            ? { slot: value.slot, action: provide(value.action) }
+            : { slot: value.slot, effect: provide(value.effect) };
+    return {
+        context,
+        provide,
+        command,
+        program: (options) => program({
+            ...options,
+            update: (model, message) => {
+                const next = options.update(model, message);
+                return {
+                    model: next.model,
+                    ...(next.cancel ? { cancel: next.cancel } : {}),
+                    ...(next.commands ? { commands: next.commands.map(command) } : {}),
+                };
+            },
+        }),
+    };
+}
+export const defaultUiRuntime = uiRuntime(Context.empty());

package/dist/session.d.ts

@@ -0,0 +1,65 @@
+import type { Query } from './query.js';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import type { UiLoad, UiModel } from './cache.js';
+import { type UiPage } from './cache.js';
+/** Explicit ownership for the application's DOM and Telegram adapters. */
+export declare function lifetime(): {
+    add(cleanup: () => void): void;
+    dispose(): void;
+    readonly disposed: boolean;
+};
+export type Read<A> = () => A;
+export interface SessionContext<R = never> {
+    readonly cache: UiModel<R>;
+    readonly changed: () => void;
+}
+/** Explicit request selection. Reads are Effect values; no tracking context or reactive props. */
+export declare function resource<A>(context: SessionContext, namespace?: string): {
+    select(selected: string | undefined, load: () => UiLoad<A>): void;
+    read: () => AsyncResult.AsyncResult<A, unknown>;
+    refresh: () => void;
+    dispose: () => void;
+};
+/**
+ * Idempotent query reconciliation for snapshot ticks. Freshness is checked when entering a
+ * selection (including remount), not on every same-key tick; refresh explicitly revalidates.
+ */
+export declare function queryResource<Args, A, E, R>(context: SessionContext<R>, definition: Query<Args, A, E, NoInfer<R>>): {
+    select(args: Args | undefined): void;
+    read: () => AsyncResult.AsyncResult<A, E>;
+    refresh: () => void;
+    dispose: () => void;
+};
+export declare function pagedResource<A, Cursor>(context: SessionContext, itemKey: (item: A) => string): {
+    select(selected: string | undefined, load: (cursor: Cursor | undefined) => UiLoad<UiPage<A, Cursor>>): void;
+    snapshot(): {
+        items: A[];
+        totalCount: number | undefined;
+        loading: boolean;
+        loadingMore: boolean;
+        hasMore: boolean;
+        error: string;
+    };
+    more: () => void | undefined;
+    refresh: () => void | undefined;
+    dispose: () => void;
+};
+/** Application selectors run once per explicit input version, with optional prior output sharing. */
+export declare function projectionCache(): {
+    invalidate: () => void;
+    select: {
+        <A>(compute: (previous: A) => A, initial: A): () => A;
+        <A>(compute: (previous: A | undefined) => A): () => A;
+    };
+};
+interface OwnedSession {
+    dispose(): void;
+    refresh?(): void;
+    subscribe?(changed: () => void): () => void;
+}
+/** One declaration owns subscriptions, refresh order and disposal for a group of sessions. */
+export declare function sessionGroup(sessions: readonly OwnedSession[], changed: () => void): {
+    refresh: () => void;
+    dispose: () => void;
+};
+export {};

package/dist/session.js

@@ -0,0 +1,186 @@
+import { runAll } from './errors.js';
+import { Cause, Option } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import * as Atom from 'effect/unstable/reactivity/Atom';
+import { loadEffect, makePagedResource } from './cache.js';
+/** Explicit ownership for the application's DOM and Telegram adapters. */
+export function lifetime() {
+    const cleanups = [];
+    let disposed = false;
+    return {
+        add(cleanup) {
+            if (disposed)
+                cleanup();
+            else
+                cleanups.push(cleanup);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            runAll(cleanups.splice(0).reverse());
+        },
+        get disposed() {
+            return disposed;
+        },
+    };
+}
+/** Explicit request selection. Reads are Effect values; no tracking context or reactive props. */
+export function resource(context, namespace) {
+    let key, atom;
+    let stop;
+    const initial = AsyncResult.initial();
+    return {
+        select(selected, load) {
+            const next = selected === undefined
+                ? undefined
+                : `${context.cache.registry.get(context.cache.generation)}:${selected}`;
+            if (next === key)
+                return;
+            stop?.();
+            stop = undefined;
+            key = next;
+            atom =
+                next === undefined
+                    ? undefined
+                    : namespace
+                        ? context.cache.resource(`${namespace}:${selected}`, load)
+                        : Atom.make(loadEffect(load)).pipe(Atom.setIdleTTL(0));
+            if (atom)
+                stop = context.cache.registry.subscribe(atom, context.changed, { immediate: true });
+            context.changed();
+        },
+        read: () => (atom ? context.cache.registry.get(atom) : initial),
+        refresh: () => {
+            if (atom)
+                context.cache.registry.refresh(atom);
+        },
+        dispose: () => {
+            stop?.();
+            stop = undefined;
+            atom = undefined;
+            key = undefined;
+        },
+    };
+}
+/**
+ * Idempotent query reconciliation for snapshot ticks. Freshness is checked when entering a
+ * selection (including remount), not on every same-key tick; refresh explicitly revalidates.
+ */
+export function queryResource(context, definition) {
+    let key;
+    let generation = -1;
+    let atom;
+    let stop;
+    let disposed = false;
+    const initial = AsyncResult.initial();
+    return {
+        select(args) {
+            if (disposed)
+                return;
+            const nextGeneration = context.cache.registry.get(context.cache.generation);
+            const nextKey = args === undefined ? undefined : definition.key(args);
+            if (nextKey === key && nextGeneration === generation)
+                return;
+            stop?.();
+            stop = undefined;
+            key = nextKey;
+            generation = nextGeneration;
+            atom = args === undefined ? undefined : context.cache.query(definition, args);
+            if (atom)
+                stop = context.cache.registry.subscribe(atom, context.changed, { immediate: true });
+            context.changed();
+        },
+        read: () => atom && !disposed && generation === context.cache.registry.get(context.cache.generation)
+            ? context.cache.registry.get(atom)
+            : initial,
+        refresh: () => {
+            if (atom && !disposed)
+                context.cache.registry.refresh(atom);
+        },
+        dispose: () => {
+            disposed = true;
+            stop?.();
+            stop = undefined;
+            atom = undefined;
+            key = undefined;
+        },
+    };
+}
+export function pagedResource(context, itemKey) {
+    let key, page, stop;
+    const initial = AsyncResult.initial();
+    const state = () => (page ? context.cache.registry.get(page.atom) : initial);
+    return {
+        select(selected, load) {
+            const next = selected === undefined
+                ? undefined
+                : `${context.cache.registry.get(context.cache.generation)}:${selected}`;
+            if (next === key)
+                return;
+            stop?.();
+            stop = undefined;
+            key = next;
+            page =
+                next === undefined ? undefined : makePagedResource(context.cache.registry, load, itemKey);
+            if (page)
+                stop = context.cache.registry.subscribe(page.atom, context.changed, { immediate: true });
+            context.changed();
+        },
+        snapshot() {
+            const result = state(), value = Option.getOrUndefined(AsyncResult.value(result));
+            return {
+                items: value?.items ?? [],
+                totalCount: value?.totalCount,
+                loading: result.waiting && !value,
+                loadingMore: result.waiting && Boolean(value),
+                hasMore: value?.next !== undefined,
+                error: AsyncResult.isFailure(result) ? String(Cause.squash(result.cause)) : '',
+            };
+        },
+        more: () => page?.more(),
+        refresh: () => page?.refresh(),
+        dispose: () => {
+            stop?.();
+            stop = undefined;
+            page = undefined;
+            key = undefined;
+        },
+    };
+}
+/** Application selectors run once per explicit input version, with optional prior output sharing. */
+export function projectionCache() {
+    let version = 0;
+    function select(compute, initial) {
+        let seen = -1, value = initial;
+        return () => {
+            if (seen !== version) {
+                value = compute(value);
+                seen = version;
+            }
+            return value;
+        };
+    }
+    return {
+        invalidate: () => {
+            version++;
+        },
+        select,
+    };
+}
+/** One declaration owns subscriptions, refresh order and disposal for a group of sessions. */
+export function sessionGroup(sessions, changed) {
+    const scope = lifetime();
+    for (const session of sessions) {
+        scope.add(() => session.dispose());
+        if (session.subscribe)
+            scope.add(session.subscribe(changed));
+    }
+    return {
+        refresh: () => {
+            if (!scope.disposed)
+                runAll(sessions.map((session) => () => session.refresh?.()));
+        },
+        dispose: () => scope.dispose(),
+    };
+}

package/dist/share.d.ts

@@ -0,0 +1,2 @@
+/** Share JSON-shaped data; Blob, typed arrays and class instances retain their own identity. */
+export declare function shareValue<T>(previous: T, next: T): T;

package/dist/share.js

@@ -0,0 +1,40 @@
+// Immutable snapshots can reach the renderer through several projections. Reuse an
+// already compared object pair without retaining either snapshot after its owners release it.
+const sharedPairs = new WeakMap();
+/** Share JSON-shaped data; Blob, typed arrays and class instances retain their own identity. */
+export function shareValue(previous, next) {
+    if (Object.is(previous, next))
+        return previous;
+    if (!previous || !next || typeof previous !== 'object' || typeof next !== 'object')
+        return next;
+    const array = Array.isArray(next);
+    if (array !== Array.isArray(previous))
+        return next;
+    if (!array &&
+        (Object.getPrototypeOf(next) !== Object.prototype ||
+            Object.getPrototypeOf(previous) !== Object.prototype))
+        return next;
+    let pairs = sharedPairs.get(previous);
+    if (pairs?.has(next))
+        return pairs.get(next);
+    const old = previous;
+    const value = next;
+    const keys = Object.keys(value);
+    let equal = keys.length === Object.keys(old).length;
+    let unchangedNext = true;
+    const shared = array ? [] : {};
+    for (const key of keys) {
+        shared[key] = shareValue(old[key], value[key]);
+        if (!Object.hasOwn(old, key) || shared[key] !== old[key])
+            equal = false;
+        if (shared[key] !== value[key])
+            unchangedNext = false;
+    }
+    const result = equal ? previous : unchangedNext ? next : shared;
+    if (!pairs) {
+        pairs = new WeakMap();
+        sharedPairs.set(previous, pairs);
+    }
+    pairs.set(next, result);
+    return result;
+}

package/dist/state.d.ts

@@ -0,0 +1,2 @@
+/** Shallow immutable update; unchanged fields preserve identity and skip publication. */
+export declare function patchModel<Model extends object>(model: Model, patch: Partial<NoInfer<Model>>): Model;

package/dist/state.js

@@ -0,0 +1,7 @@
+/** Shallow immutable update; unchanged fields preserve identity and skip publication. */
+export function patchModel(model, patch) {
+    return Reflect.ownKeys(patch).some((key) => Object.prototype.propertyIsEnumerable.call(patch, key) &&
+        (!Object.hasOwn(model, key) || !Object.is(model[key], patch[key])))
+        ? { ...model, ...patch }
+        : model;
+}

package/dist/task.d.ts

@@ -0,0 +1,53 @@
+import { Effect } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import type { View } from './dom.js';
+import { type Send } from './program.js';
+import { type UiRuntime } from './runtime.js';
+export type TaskModel<Props, State, A, E = unknown> = State & {
+    readonly props: Props;
+    readonly task: AsyncResult.AsyncResult<A, E>;
+};
+export type TaskMessage<State, Input> = {
+    type: 'Run';
+    input: Input;
+} | {
+    type: 'Fields';
+    fields: Partial<State> & {
+        props?: never;
+        task?: never;
+    };
+} | {
+    type: 'Cancel';
+};
+/**
+ * One owned async action and local editable fields; policy is part of its public behavior.
+ * Compatibility factory for existing single-task components. New components can use
+ * defineTasks(...).tasks(...).view(view(...)) to establish inference before JSX.
+ */
+export declare function taskComponent<Props, State extends object, Input, A, E = unknown, R = never>(definition: {
+    init: (props: Props) => State & {
+        props?: never;
+        task?: never;
+    };
+    identity?: (props: Props) => unknown;
+    task: {
+        policy: 'drop' | 'replace';
+        run: (model: State & {
+            readonly props: Props;
+        }, input: Input) => Effect.Effect<A, E, R>;
+    };
+    view: View<TaskModel<Props, State, A, E>, TaskMessage<State, Input>>;
+} & ([R] extends [never] ? {
+    runtime?: UiRuntime<R>;
+} : {
+    runtime: UiRuntime<R>;
+})): View<Props, never>;
+/** Stable methods when bound once in a compiled view's const declaration. */
+export declare function taskControls<State, Input>(send: Send<TaskMessage<State, Input>>): {
+    run: (input: Input) => void;
+    patch: (fields: Partial<State> & {
+        props?: never;
+        task?: never;
+    }) => void;
+    cancel: () => void;
+};

package/dist/task.js

@@ -0,0 +1,70 @@
+import { Cause, Effect, Option } from 'effect';
+import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import { component } from './component.js';
+import { effectCommand } from './program.js';
+import { patchModel } from './state.js';
+import { defaultUiRuntime } from './runtime.js';
+/**
+ * One owned async action and local editable fields; policy is part of its public behavior.
+ * Compatibility factory for existing single-task components. New components can use
+ * defineTasks(...).tasks(...).view(view(...)) to establish inference before JSX.
+ */
+export function taskComponent(definition) {
+    const runtime = definition.runtime ?? defaultUiRuntime;
+    const init = (props) => ({
+        ...definition.init(props),
+        props,
+        task: AsyncResult.initial(),
+    });
+    return component({
+        init,
+        receive: (model, props) => definition.identity &&
+            !Object.is(definition.identity(model.props), definition.identity(props))
+            ? { model: init(props), cancel: ['task'] }
+            : { model: Object.is(model.props, props) ? model : { ...model, props } },
+        update: (model, message) => {
+            switch (message.type) {
+                case 'Fields': {
+                    const next = patchModel(model, message.fields);
+                    return {
+                        model: next === model ? model : { ...next, props: model.props, task: model.task },
+                    };
+                }
+                case 'Run':
+                    if (definition.task.policy === 'drop' && model.task.waiting)
+                        return { model };
+                    return {
+                        model: { ...model, task: AsyncResult.waiting(model.task) },
+                        commands: [
+                            effectCommand('task', () => runtime.provide(definition.task.run(model, message.input)), {
+                                onSuccess: (value) => ({ type: 'Succeeded', value }),
+                                onFailure: (cause) => ({ type: 'Failed', cause }),
+                            }),
+                        ],
+                    };
+                case 'Cancel':
+                    return { model: { ...model, task: AsyncResult.initial() }, cancel: ['task'] };
+                case 'Succeeded':
+                    return { model: { ...model, task: AsyncResult.success(message.value) } };
+                case 'Failed':
+                    return {
+                        model: {
+                            ...model,
+                            task: AsyncResult.failureWithPrevious(message.cause, {
+                                previous: Option.some(model.task),
+                            }),
+                        },
+                    };
+            }
+        },
+        view: definition.view,
+    });
+}
+/** Stable methods when bound once in a compiled view's const declaration. */
+export function taskControls(send) {
+    return {
+        run: (input) => send({ type: 'Run', input }),
+        patch: (fields) => send({ type: 'Fields', fields }),
+        cancel: () => send({ type: 'Cancel' }),
+    };
+}