effectweb 0.3.1 → 0.5.0

package/dist/query.d.ts

@@ -1,5 +1,7 @@
-import type { Effect } from 'effect';
+import type * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
 import { type QueryDefinition } from './query-internals.js';
+import type { Snapshot } from './snapshot.js';
 /** Canonical data identity: plain objects, dense arrays, and finite scalar values. */
 export type QueryKey = string | number | boolean | null | undefined | readonly QueryKey[] | {
     readonly [key: string]: QueryKey;
@@ -14,18 +16,27 @@ declare const queryType: unique symbol;
 /** An opaque typed definition. Every request argument participates in cache identity. */
 export interface Query<Args, A, E = never, R = never> {
     readonly name: string;
-    readonly [queryType]: (args: Args) => Effect.Effect<A, E, R>;
+    readonly [queryType]: (args: Args) => Effect.Effect<A, E, R | Scope.Scope>;
 }
 type Definition<Args, A, E, R> = Omit<QueryDefinition<Args, A, E, R>, 'staleTime'> & {
     readonly staleTime?: number;
     /** Custom projections can silently reuse a different request's result. */
     readonly key?: never;
 };
-export declare function query<Args, A, E = never, R = never>(definition: Definition<Args, A, E, R> & (Args extends QueryArgs<Args> ? unknown : {
-    readonly nonSerializableQueryArguments: never;
-})): Query<Args, A, E, R>;
+/** Encode the complete argument value explicitly when its representation is not plain data. */
+export type QueryEncoding<Args> = [Args] extends [QueryArgs<Args>] ? {
+    readonly encode?: (args: Snapshot<Args>) => QueryKey;
+} : {
+    readonly encode: (args: Snapshot<Args>) => QueryKey;
+};
+/** Shared identity contract for lookup, selection, writes, invalidation and pagination. */
+export declare function encodeQueryArguments<Args, A, E, R>(definition: Query<Args, A, E, R>, args: Args | Snapshot<Args>): string;
+export declare function query<Args, A, E = never, R = never>(definition: Definition<Args, A, E, R> & {
+    readonly encode: (args: Snapshot<Args>) => QueryKey;
+}): Query<Args, A, E, R>;
+export declare function query<Args, A, E = never, R = never>(definition: Definition<Args, A, E, R> & QueryEncoding<Args>): Query<Args, A, E, R>;
 export declare function query<A, E = never, R = never>(definition: Definition<true, A, E, R> & {
-    readonly load: () => Effect.Effect<A, E, R>;
+    readonly load: () => Effect.Effect<A, E, R | Scope.Scope>;
 }): Query<true, A, E, R>;
 declare const groupType: unique symbol;
 export type QueryGroup = symbol & {

package/dist/query.js

@@ -1,4 +1,4 @@
-import { registerQuery } from './query-internals.js';
+import { registerQuery, queryDefinition } from './query-internals.js';
 /** Shared by cache lookup and resource reconciliation. Object property order is irrelevant. */
 export function encodeQueryKey(key) {
     const ancestors = new Set();
@@ -53,9 +53,12 @@ export function encodeQueryKey(key) {
     };
     return encode(key);
 }
+/** Shared identity contract for lookup, selection, writes, invalidation and pagination. */
+export function encodeQueryArguments(definition, args) {
+    const config = queryDefinition(definition);
+    return encodeQueryKey(config.encode ? config.encode(args) : args);
+}
 export function query(definition) {
-    if ('key' in definition)
-        throw new TypeError('Query identity includes all arguments. Remove key and provide services through the Effect environment.');
     const staleTime = definition.staleTime ?? Infinity;
     if (Number.isNaN(staleTime) || staleTime < 0)
         throw new RangeError('Query staleTime must be nonnegative.');

package/dist/render.d.ts

@@ -0,0 +1,17 @@
+import * as Effect from 'effect/Effect';
+import * as Scope from 'effect/Scope';
+import { type Mounted, type View } from './dom.js';
+import type { Source } from './source.js';
+import type { Send } from './program.js';
+import { type ReportError } from './errors.js';
+/**
+ * Mount values or Effect-based view setup in a child resource scope.
+ * The surrounding Effect owns the mount; the source keeps its own lifetime.
+ */
+export declare function mount<M, Message = never, E = never, R = never>(parent: Node, definition: View<M, Message> | Effect.Effect<View<M, Message>, E, R>, source: Source<M> & ([Message] extends [never] ? {
+    readonly send?: Send<Message>;
+} : {
+    readonly send: Send<Message>;
+}), options?: {
+    readonly onError?: ReportError;
+}): Effect.Effect<Mounted, E, R | Scope.Scope>;

package/dist/render.js

@@ -0,0 +1,48 @@
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Scope from 'effect/Scope';
+import { mountViewWithSettlement, unboundSend } from './dom.js';
+import { makeUiRuntime } from './runtime.js';
+import { reportError, reportSafely } from './errors.js';
+import { Settlement } from './settlement.js';
+/**
+ * Mount values or Effect-based view setup in a child resource scope.
+ * The surrounding Effect owns the mount; the source keeps its own lifetime.
+ */
+export function mount(parent, definition, source, options = {}) {
+    return Effect.gen(function* () {
+        const lifetime = yield* Effect.acquireRelease(Effect.sync(() => {
+            const scope = Scope.makeUnsafe();
+            let closingExit;
+            const closed = Effect.runSync(Effect.cached(Effect.uninterruptible(Effect.suspend(() => Scope.close(scope, closingExit ?? Exit.void)))));
+            const beginClose = (exit) => {
+                closingExit ??= exit;
+                return closed;
+            };
+            const close = (exit) => Effect.suspend(() => beginClose(exit));
+            return { scope, close, beginClose };
+        }), (lifetime, exit) => lifetime.close(exit));
+        return yield* Effect.gen(function* () {
+            const runtime = yield* makeUiRuntime();
+            const view = Effect.isEffect(definition) ? yield* definition : definition;
+            const settlement = new Settlement(runtime);
+            // Acquisition can throw after starting child cleanup, before a Mounted exists.
+            yield* Effect.addFinalizer(() => settlement.wait());
+            const mounted = yield* Effect.acquireRelease(Effect.sync(() => mountViewWithSettlement(parent, view, source, { ...options, send: source.send ?? unboundSend }, settlement)), (mounted, exit) => Effect.suspend(() => {
+                settlement.exit = exit;
+                return mounted.close();
+            }));
+            const close = lifetime.close(Exit.void);
+            const dispose = () => {
+                // Claim the exit before user unsubscriptions can reenter application shutdown.
+                const closed = lifetime.beginClose(Exit.void);
+                mounted.dispose();
+                Effect.runFork(closed).addObserver((exit) => {
+                    if (exit._tag === 'Failure')
+                        reportSafely(options.onError ?? reportError, exit.cause);
+                });
+            };
+            return Object.assign(dispose, { dispose, close: () => close });
+        }).pipe(Scope.provide(lifetime.scope), Effect.onError((cause) => lifetime.close(Exit.failCause(cause))));
+    });
+}

package/dist/resource.d.ts

@@ -1,7 +1,8 @@
 import type { Snapshot } from './snapshot.js';
+import type * as Scope from 'effect/Scope';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import type { UiLoad } from './load.js';
-import { type UiRuntime } from './runtime.js';
+import type { UiRuntime } from './runtime.js';
 import type { View } from './dom.js';
 export interface ResourceModel<Props, A, E = unknown> {
     readonly props: Props;
@@ -17,11 +18,11 @@ export declare const resourceError: (result: AsyncResult.AsyncResult<unknown, un
 export declare function resourceComponent<Props, A, E = unknown, R = never>(definition: {
     request: (props: Snapshot<Props>) => {
         key: string;
-        load: () => UiLoad<A, E, R>;
+        load: () => UiLoad<A, E, R | Scope.Scope>;
         delay?: number;
     } | undefined;
     view: View<ResourceModel<Props, A, E>, ResourceMessage>;
-} & ([R] extends [never] ? {
+} & ([Exclude<R, Scope.Scope>] extends [never] ? {
     runtime?: UiRuntime<R>;
 } : {
     runtime: UiRuntime<R>;

package/dist/resource.js

@@ -1,9 +1,10 @@
 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 { loadEffect } from './load.js';
 import { component } from './component.js';
-import { defaultUiRuntime } from './runtime.js';
 import { effectCommand } from './program.js';
 const commandLoad = commandSlot('load');
 export const available = (result) => Option.getOrUndefined(AsyncResult.value(result));
@@ -15,7 +16,7 @@ export const resourceError = (result) => {
 };
 /** 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 runtime = definition.runtime;
     const request = (model, retry = false) => {
         const selected = definition.request(model.props);
         if (!retry && selected?.key === model.key)
@@ -32,9 +33,14 @@ export function resourceComponent(definition) {
                 result: AsyncResult.waiting(selected.key === model.key ? model.result : AsyncResult.initial()),
             },
             commands: [
-                effectCommand(commandLoad, () => runtime.provide(selected.delay
-                    ? Effect.sleep(selected.delay).pipe(Effect.andThen(loadEffect(selected.load)))
-                    : loadEffect(selected.load)), {
+                effectCommand(commandLoad, () => {
+                    const work = selected.delay
+                        ? Effect.sleep(selected.delay).pipe(Effect.andThen(loadEffect(selected.load)))
+                        : loadEffect(selected.load);
+                    return runtime
+                        ? runtime.provideScoped(work)
+                        : work;
+                }, {
                     policy: 'replace',
                     onSuccess: (value) => ({ type: 'Loaded', value }),
                     onFailure: (cause) => ({ type: 'Failed', cause }),

package/dist/runtime.d.ts

@@ -1,10 +1,19 @@
 import type { Snapshot } from './snapshot.js';
-import { Context, Effect } from 'effect';
+import * as Context from 'effect/Context';
+import * as Clock from 'effect/Clock';
+import * as Effect from 'effect/Effect';
+import type * as Fiber from 'effect/Fiber';
+import * as Scope from 'effect/Scope';
 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 clock: Clock.Clock;
+    /** Execute work with a fresh resource scope and the captured application context. */
+    readonly runFork: <A, E>(effect: Effect.Effect<A, E, R | Scope.Scope>) => Fiber.Fiber<A, E>;
     readonly provide: <A, E>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E>;
+    /** Supply services while preserving the resource owner's scope. */
+    readonly provideScoped: <A, E>(effect: Effect.Effect<A, E, R | Scope.Scope>) => Effect.Effect<A, E, Scope.Scope>;
     readonly command: <M>(command: Command<M, R>) => Command<M>;
     readonly program: <M, Msg>(options: {
         initial: M | Snapshot<M>;
@@ -14,4 +23,6 @@ export interface UiRuntime<R> {
     }) => RunningProgram<M, Msg>;
 }
 export declare function uiRuntime<R>(context: Context.Context<R>): UiRuntime<R>;
+/** Capture the current Effect environment. The surrounding scope owns all started fibers. */
+export declare const makeUiRuntime: <R = never>() => Effect.Effect<UiRuntime<R>, never, R | Scope.Scope>;
 export declare const defaultUiRuntime: UiRuntime<never>;

package/dist/runtime.js

@@ -1,18 +1,40 @@
-import { Context, Effect, Stream } from 'effect';
+import * as Context from 'effect/Context';
+import * as Clock from 'effect/Clock';
+import * as Effect from 'effect/Effect';
+import * as FiberSet from 'effect/FiberSet';
+import * as Scope from 'effect/Scope';
+import * as Stream from 'effect/Stream';
 import { program } from './program.js';
 export function uiRuntime(context) {
+    return createRuntime(context, Effect.runForkWith(context));
+}
+/** Capture the current Effect environment. The surrounding scope owns all started fibers. */
+export const makeUiRuntime = () => Effect.gen(function* () {
+    const context = yield* Effect.context();
+    const fibers = yield* FiberSet.make();
+    const run = yield* FiberSet.runtime(fibers)();
+    return createRuntime(context, run);
+});
+function createRuntime(context, run) {
     const provide = (effect) => Effect.provideContext(effect, context);
     const command = (value) => value.stream
-        ? { ...value, stream: value.stream.pipe(Stream.provideContext(context)) }
+        ? {
+            ...value,
+            stream: Stream.unwrap(Effect.map(Effect.scope, (scope) => value.stream.pipe(Stream.provideContext(Context.add(context, Scope.Scope, scope))))),
+        }
         : value.action
-            ? { ...value, action: provide(value.action) }
-            : { ...value, effect: provide(value.effect) };
+            ? { ...value, action: provide(Effect.scoped(value.action)) }
+            : { ...value, effect: provide(Effect.scoped(value.effect)) };
     return {
         context,
+        clock: Context.get(context, Clock.Clock),
+        runFork: (effect) => run(Effect.scoped(effect)),
         provide,
+        provideScoped: (effect) => Effect.flatMap(Effect.scope, (scope) => provide(Scope.provide(effect, scope))),
         command,
         program: (options) => program({
             ...options,
+            runtime: { runFork: (effect) => run(Effect.scoped(effect)) },
             update: (model, message) => {
                 const next = options.update(model, message);
                 return {
@@ -24,4 +46,4 @@ export function uiRuntime(context) {
         }),
     };
 }
-export const defaultUiRuntime = uiRuntime(Context.empty());
+export const defaultUiRuntime = /* @__PURE__ */ uiRuntime(Context.empty());

package/dist/session.d.ts

@@ -1,3 +1,4 @@
+import type * as Scope from 'effect/Scope';
 import type { Snapshot } from './snapshot.js';
 import { type Query } from './query.js';
 import type { DisposableOwner } from './owner.js';
@@ -28,8 +29,8 @@ export interface QueryResource<Args, A, E = never> {
 export declare function queryResource<Args, A, E, R>(context: {
     cache: QueryCache<R>;
     changed?: () => void;
-}, definition: Query<Args, A, E, NoInfer<R>>): QueryResource<Args, A, E>;
-export declare function observeQuery<Args, A, E, R>(owner: DisposableOwner, cache: QueryCache<R>, definition: Query<Args, A, E, NoInfer<R>>, changed: (result: AsyncResult.AsyncResult<Snapshot<A>, E>) => void): QueryResource<Args, A, E>;
+}, definition: Query<Args, A, E, NoInfer<R> | Scope.Scope>): QueryResource<Args, A, E>;
+export declare function observeQuery<Args, A, E, R>(owner: DisposableOwner, cache: QueryCache<R>, definition: Query<Args, A, E, NoInfer<R> | Scope.Scope>, changed: (result: AsyncResult.AsyncResult<Snapshot<A>, E>) => void): QueryResource<Args, A, E>;
 /** Application selectors run once per explicit input version, with optional prior output sharing. */
 export declare function projectionCache(): {
     invalidate: () => void;

package/dist/session.js

@@ -1,5 +1,5 @@
 import { runAll, reportError, reportSafely } from './errors.js';
-import { encodeQueryKey } from './query.js';
+import { encodeQueryArguments } from './query.js';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import * as Atom from 'effect/unstable/reactivity/Atom';
 import { cacheInternals } from './cache-internals.js';
@@ -108,11 +108,14 @@ export function queryResource(context, definition) {
             if (disposed || internal.disposed())
                 return;
             const nextGeneration = internal.registry.get(internal.generation);
-            const nextKey = args === undefined ? undefined : encodeQueryKey(args);
+            const nextKey = args === undefined ? undefined : encodeQueryArguments(definition, args);
             if (nextKey === key && nextGeneration === generation)
                 return;
             const selected = ++revision;
             disconnect();
+            // Releasing the previous query can run finalizers that select or dispose again.
+            if (disposed || selected !== revision)
+                return;
             key = nextKey;
             generation = nextGeneration;
             const nextAtom = args === undefined ? undefined : internal.query(definition, args);
@@ -192,10 +195,17 @@ export function projectionCache() {
 }
 export function sessionGroup(sessions, changed) {
     const scope = lifetime();
-    for (const session of sessions) {
+    for (const session of sessions)
         scope.add(() => session.dispose());
-        if (session.subscribe)
-            scope.add(session.subscribe(changed));
+    try {
+        for (const session of sessions) {
+            if (session.subscribe)
+                scope.add(session.subscribe(changed));
+        }
+    }
+    catch (error) {
+        scope.dispose();
+        throw error;
     }
     return {
         refresh: () => {

package/dist/settlement.d.ts

@@ -1,7 +1,14 @@
 /** Internal completion accounting, including reentrant acquisition before a fiber is available. */
 export declare class Settlement {
+    readonly runtime?: UiRuntime<never> | undefined;
+    constructor(runtime?: UiRuntime<never> | undefined);
+    /** Exit of the owning mount; element replacement/removal uses a successful exit. */
+    exit: Exit.Exit<unknown, unknown>;
     private pending;
     private waiters;
     begin(): () => void;
-    wait(): Promise<void>;
+    wait(): Effect.Effect<void>;
 }
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import type { UiRuntime } from './runtime.js';

package/dist/settlement.js

@@ -1,7 +1,13 @@
 /** Internal completion accounting, including reentrant acquisition before a fiber is available. */
 export class Settlement {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    /** Exit of the owning mount; element replacement/removal uses a successful exit. */
+    exit = Exit.void;
     pending = 0;
-    waiters = [];
+    waiters = new Set();
     begin() {
         this.pending++;
         let finished = false;
@@ -11,17 +17,23 @@ export class Settlement {
             finished = true;
             if (--this.pending)
                 return;
-            for (const done of this.waiters)
+            const waiters = [...this.waiters];
+            this.waiters.clear();
+            for (const done of waiters)
                 done();
-            this.waiters.length = 0;
         };
     }
     wait() {
-        return new Promise((done) => {
-            if (this.pending)
-                this.waiters.push(done);
-            else
-                done();
+        return Effect.callback((resume) => {
+            if (!this.pending)
+                return resume(Effect.void);
+            const done = () => resume(Effect.void);
+            this.waiters.add(done);
+            return Effect.sync(() => {
+                this.waiters.delete(done);
+            });
         });
     }
 }
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';

package/dist/snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { Effect } from 'effect';
+import type * as Effect from 'effect/Effect';
 import type * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 /** Mark an application service as opaque to snapshot typing; this is a type-only brand. */
 export declare const snapshotOpaque: unique symbol;

package/dist/snapshot.js

@@ -1,19 +1,19 @@
 import { isAsyncResult } from 'effect/unstable/reactivity/AsyncResult';
-const checked = new WeakSet();
+const protectedValues = new WeakSet();
 /** Protect published plain data in every build. Opaque objects keep their own lifecycle. */
 export function protectSnapshot(value) {
     const seen = new Set();
     const plain = [];
-    const validate = (item) => {
-        if (!item || typeof item !== 'object' || checked.has(item) || seen.has(item))
+    const visit = (item) => {
+        if (!item || typeof item !== 'object' || protectedValues.has(item) || seen.has(item))
             return;
         seen.add(item);
         // Effect wrappers remain opaque, but their successful UI data is plain data.
         if (isAsyncResult(item)) {
             if (item._tag === 'Success')
-                validate(item.value);
+                visit(item.value);
             else if (item._tag === 'Failure' && item.previousSuccess._tag === 'Some')
-                validate(item.previousSuccess.value);
+                visit(item.previousSuccess.value);
             return;
         }
         const prototype = Object.getPrototypeOf(item);
@@ -21,18 +21,16 @@ export function protectSnapshot(value) {
             return;
         for (const key of Reflect.ownKeys(item)) {
             const descriptor = Object.getOwnPropertyDescriptor(item, key);
-            if (!Object.hasOwn(descriptor, 'value'))
-                throw new Error(`Snapshot data cannot contain an accessor (${String(key)}). Materialize its value before publication; keep services in opaque instances.`);
-            validate(descriptor.value);
+            if (Object.hasOwn(descriptor, 'value'))
+                visit(descriptor.value);
         }
         plain.push(item);
     };
-    // Validate the complete graph before caching any proof. A rejected cyclic graph
-    // must not make a later publication skip validation through a previously seen child.
-    validate(value);
+    // Traverse stored data without invoking application getters.
+    visit(value);
     for (const item of plain)
         Object.freeze(item);
     for (const item of seen)
-        checked.add(item);
+        protectedValues.add(item);
     return value;
 }

package/dist/source.d.ts

@@ -0,0 +1,38 @@
+import * as Effect from 'effect/Effect';
+import type * as Scope from 'effect/Scope';
+import * as Stream from 'effect/Stream';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
+import type * as Atom from 'effect/unstable/reactivity/Atom';
+import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
+import { type Snapshot } from './snapshot.js';
+/** A current immutable value and its publications. Observation does not own the producer. */
+export interface Source<A> {
+    readonly model: () => Snapshot<A>;
+    readonly subscribe: (listener: (value: Snapshot<A>) => void) => () => void;
+}
+/** Select explicit inputs. Equal results retain their identity and do not notify subscribers. */
+export declare function mapSource<A, B>(source: Source<A>, project: (value: Snapshot<A>) => B | Snapshot<B>, equals?: (previous: Snapshot<B>, next: Snapshot<B>) => boolean): Source<B>;
+/** Observe a snapshot stream in the current Effect scope. Handle typed stream errors as values upstream. */
+export declare const fromStream: <A, R>(stream: Stream.Stream<A, never, R>, initial: A | Snapshot<A>) => Effect.Effect<Source<A>, never, R | Scope.Scope>;
+/** Observe the existing ref; closing the observation leaves the ref and its other users alive. */
+export declare const fromSubscriptionRef: <A>(ref: SubscriptionRef.SubscriptionRef<A>) => Effect.Effect<Source<A>, never, Scope.Scope>;
+export declare function fromAtom<A>(atom: Atom.Atom<A>): Effect.Effect<Source<A>, never, AtomRegistry.AtomRegistry | Scope.Scope>;
+export declare function fromAtom<A>(atom: Atom.Atom<A>, registry: AtomRegistry.AtomRegistry): Effect.Effect<Source<A>, never, Scope.Scope>;
+/** A batched publication boundary for independently owned sessions with explicit invalidation. */
+export declare function projectionSource<Model>(options: {
+    invalidate?: () => void;
+    refresh?: () => void;
+    project: () => Model | Snapshot<Model>;
+    reconcile?: (previous: Snapshot<Model>, next: Model | Snapshot<Model>) => Model | Snapshot<Model>;
+    afterPublish?: () => void;
+}): {
+    readonly disposed: boolean;
+    changed: () => void;
+    watch(source: {
+        subscribe: (changed: () => void) => () => void;
+    }): () => void;
+    start(): void;
+    model(this: void): Snapshot<Model>;
+    subscribe(this: void, listener: (model: Snapshot<Model>) => void): () => void;
+    dispose(): void;
+};