effectweb 0.3.0 → 0.4.0

package/dist/mount.js

@@ -1,5 +1,8 @@
 import { reportError, reportSafely } from './errors.js';
-import { Effect, Fiber } from 'effect';
+import * as Cause from 'effect/Cause';
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
 import { defaultUiRuntime } from './runtime.js';
 export { Portal } from './dom.js';
 /** Element-owned work. Changed acquisition functions replace and interrupt the prior lifetime. */
@@ -26,34 +29,92 @@ export function domBinding(data, acquire, ...provided) {
         },
     };
 }
-export function startMount(element, mount, report = reportError) {
+/** Allocate the lifetime before acquisition so reentrant publications can update or close it. */
+export function prepareMount(element, mount, report = reportError) {
     let data = mount.data;
-    const work = mount.acquire(element, () => data);
-    const fiber = Effect.isEffect(work) ? Effect.runFork(work) : undefined;
+    let work;
+    let fiber;
+    let started = false;
     let disposed = false;
-    fiber?.addObserver((exit) => {
-        if (exit._tag === 'Failure' && !disposed)
-            reportSafely(report, exit.cause);
-    });
+    let released = false;
+    let changedDuringSetup = false;
+    const completed = Deferred.makeUnsafe();
+    const closed = Deferred.await(completed);
+    const finish = () => Deferred.doneUnsafe(completed, Effect.void);
+    const release = () => {
+        if (released || work === undefined || (Effect.isEffect(work) && !fiber))
+            return;
+        released = true;
+        if (fiber)
+            Effect.runFork(Fiber.interrupt(fiber));
+        else {
+            try {
+                if (typeof work === 'function')
+                    work();
+                else if ('dispose' in work)
+                    work.dispose();
+            }
+            finally {
+                finish();
+            }
+        }
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        if (!started)
+            finish();
+        else
+            release();
+    };
     return {
+        closed,
+        start() {
+            if (started || disposed)
+                return;
+            started = true;
+            try {
+                work = mount.acquire(element, () => data);
+                if (Effect.isEffect(work)) {
+                    fiber = Effect.runFork(work);
+                    fiber.addObserver((exit) => {
+                        if (exit._tag === 'Failure' && (!disposed || !Cause.hasInterruptsOnly(exit.cause)))
+                            reportSafely(report, exit.cause);
+                        finish();
+                    });
+                }
+                if (disposed)
+                    release();
+                else if (changedDuringSetup && !fiber && typeof work === 'object' && 'update' in work)
+                    work.update?.();
+            }
+            catch (error) {
+                dispose();
+                if (work === undefined)
+                    finish();
+                throw error;
+            }
+        },
+        close: () => Effect.suspend(() => {
+            dispose();
+            return closed;
+        }),
         update(next) {
-            if (next.identity !== mount.identity)
+            if (disposed || next.identity !== mount.identity)
                 return false;
             data = next.data;
-            if (!fiber && typeof work === 'object' && 'update' in work)
+            if (started && work === undefined)
+                changedDuringSetup = true;
+            else if (!fiber && typeof work === 'object' && work && 'update' in work)
                 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,
     };
 }
+export function startMount(element, mount, report = reportError) {
+    const lifetime = prepareMount(element, mount, report);
+    lifetime.start();
+    return lifetime;
+}

package/dist/owner.d.ts

@@ -1,14 +1,16 @@
 import { type Snapshot } from './snapshot.js';
-import { Effect } from 'effect';
+import * as Effect from 'effect/Effect';
 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 } from './program.js';
+interface OwnedResource {
+    dispose(): void;
+    close?(): Effect.Effect<void, unknown>;
+}
 export interface DisposableOwner {
     readonly disposed: boolean;
-    readonly own: <A extends {
-        dispose(): void;
-    }>(resource: A) => A;
+    readonly own: <A extends OwnedResource>(resource: A) => A;
 }
 export interface ModelOwner<Model extends object, R = never> extends DisposableOwner {
     readonly source: Program<Model, never>;
@@ -24,7 +26,9 @@ export interface ModelOwner<Model extends object, R = never> extends DisposableO
     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: () => Promise<void>;
+    readonly awaitIdle: (slot?: CommandSlot) => Effect.Effect<void>;
+    /** Interrupt and join work before closing owned dependencies in reverse order. */
+    readonly close: () => Effect.Effect<void, AggregateError>;
     readonly dispose: () => void;
 }
 type Options = {

package/dist/owner.js

@@ -1,5 +1,7 @@
 import { protectSnapshot } from './snapshot.js';
-import { Effect } from 'effect';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
 import { program, } from './program.js';
 import { patchModel } from './state.js';
 import { runAll, reportError } from './errors.js';
@@ -7,6 +9,7 @@ export function modelOwner(initial, options = {}) {
     let disposed = false;
     let staged;
     const cleanups = [];
+    let resourcesDisposed = false;
     const source = program({
         initial,
         ...options,
@@ -56,10 +59,29 @@ export function modelOwner(initial, options = {}) {
             return;
         disposed = true;
         source.dispose();
-        runAll(cleanups.splice(0).reverse(), options.onDefect ?? reportError);
+        resourcesDisposed = true;
+        runAll([...cleanups].reverse().map((resource) => () => resource.dispose()), options.onDefect ?? reportError);
     };
+    const closing = Effect.runSync(Effect.cached(Effect.uninterruptible(Effect.gen(function* () {
+        disposed = true;
+        const resources = cleanups.splice(0).reverse();
+        yield* source.close();
+        const errors = [];
+        for (const resource of resources) {
+            const exit = yield* Effect.exit(Effect.suspend(() => resource.close
+                ? resource.close()
+                : resourcesDisposed
+                    ? Effect.void
+                    : Effect.sync(() => resource.dispose())));
+            if (Exit.isFailure(exit))
+                errors.push(Cause.squash(exit.cause));
+        }
+        if (errors.length)
+            return yield* Effect.fail(new AggregateError(errors, 'Owner cleanup failed.'));
+    }))));
+    const close = () => 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) => {
@@ -87,11 +109,6 @@ export function modelOwner(initial, options = {}) {
             staged = batch;
             try {
                 const result = work();
-                if (result &&
-                    (typeof result === 'object' || typeof result === 'function') &&
-                    'then' in result &&
-                    typeof result.then === 'function')
-                    throw new TypeError('Model transactions must be synchronous. Run async work as an owned Effect.');
                 staged = parent;
                 if (!disposed) {
                     if (parent) {
@@ -114,11 +131,12 @@ export function modelOwner(initial, options = {}) {
         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,12 +1,13 @@
 import type { Snapshot } from './snapshot.js';
-import { Cause } from 'effect';
+import * as Cause from 'effect/Cause';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import type { UiLoad, UiPage } from './load.js';
 import { type Transition, type RunningProgram } from './program.js';
-export interface PagesModel<Props, A, Cursor> {
+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 PagesRequest = {
@@ -17,34 +18,34 @@ export type PagesRequest = {
     type: 'Refresh';
 };
 /** Low-level reducer protocol, including completions for explicit program composition. */
-export type PagesMessage<A, Cursor> = PagesRequest | {
+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> extends RunningProgram<PagesModel<Props, A, Cursor>, PagesRequest> {
+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> {
-    readonly init: (props: Props | Snapshot<Props>) => PagesModel<Props, A, Cursor> | Snapshot<PagesModel<Props, A, Cursor>>;
-    readonly receive: (model: PagesModel<Props, A, Cursor> | Snapshot<PagesModel<Props, A, Cursor>>, props: Props | Snapshot<Props>, options?: {
+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>, PagesMessage<A, Cursor>>;
-    readonly update: (model: PagesModel<Props, A, Cursor> | Snapshot<PagesModel<Props, A, Cursor>>, message: PagesMessage<A, Cursor>) => Transition<PagesModel<Props, A, Cursor>, PagesMessage<A, Cursor>>;
-    readonly create: (props: Props | Snapshot<Props>) => PagesProgram<Props, A, Cursor>;
+    }) => 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: {
+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>>;
+    load: (props: Snapshot<Props>, cursor: Snapshot<Cursor> | undefined) => UiLoad<UiPage<A, Cursor>, E, R>;
     itemKey: (item: Snapshot<A>) => string;
-}): Pagination<Props, A, Cursor>;
+}, ...provided: [R] extends [never] ? [runtime?: UiRuntime<R>] : [runtime: UiRuntime<R>]): Pagination<Props, A, Cursor, E>;

package/dist/pages.js

@@ -1,16 +1,19 @@
 import { commandSlot } from './program.js';
 import { shareData } from './sharing.js';
-import { Cause, Option } from 'effect';
+import * as Cause from 'effect/Cause';
+import * as Option from 'effect/Option';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import { effectCommand, program, } from './program.js';
+import { defaultUiRuntime } from './runtime.js';
 import { available } from './resource.js';
-const commandPage = commandSlot('page');
 /**
  * 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 function pages(definition) {
+export function pages(definition, ...provided) {
+    const runtime = provided[0] ?? defaultUiRuntime;
+    const commandPage = commandSlot('page');
     const request = (model, append) => {
         const previous = available(model.result);
         if (append && (model.result.waiting || !previous || previous.next === undefined))
@@ -21,11 +24,11 @@ export function pages(definition) {
         return {
             model: { ...model, append, result: AsyncResult.waiting(model.result) },
             commands: [
-                effectCommand(commandPage, () => definition.load(model.props, cursor), {
+                runtime.command(effectCommand(commandPage, () => definition.load(model.props, cursor), {
                     policy: 'replace',
                     onSuccess: (page) => ({ type: 'Loaded', page, append }),
                     onFailure: (cause) => ({ type: 'Failed', cause }),
-                }),
+                })),
             ],
         };
     };

package/dist/program.d.ts

@@ -1,5 +1,7 @@
 import { type Snapshot } from './snapshot.js';
-import { Cause, Effect, Stream } from 'effect';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
 export type Send<Message> = (message: Message) => void;
 /** queue retains FIFO requests; latest-queued retains only the newest pending request. */
 export type TaskPolicy = 'replace' | 'drop' | 'parallel' | 'queue' | 'latest-queued';
@@ -13,6 +15,8 @@ export declare const commandSlot: (name: string) => CommandSlot;
 export type Command<Message, R = never> = {
     readonly slot: CommandSlot;
     readonly policy: TaskPolicy;
+    /** Notification for work that never started. */
+    readonly onDiscard?: (reason: 'Cancelled' | 'Superseded' | 'Dropped') => void;
 } & ({
     readonly effect: Effect.Effect<Message, never, R>;
     readonly stream?: never;
@@ -40,15 +44,23 @@ export interface Transition<Model, Message, R = never> {
     readonly commands?: readonly Command<Message, R>[];
     readonly cancel?: readonly CommandSlot[];
 }
+export declare function mapTransition<Model, Message, Parent, ParentMessage, R = never>(transition: Transition<Model, Message, R>, maps: {
+    readonly model: (model: Snapshot<Model>) => Parent | Snapshot<Parent>;
+    readonly message: (message: Message) => ParentMessage;
+}): Transition<Parent, ParentMessage, R>;
 export interface Program<Model, Message> {
     readonly model: () => Snapshot<Model>;
     readonly send: Send<Message>;
     readonly subscribe: (listener: (model: Snapshot<Model>) => void) => () => void;
     readonly dispose: () => void;
+    readonly close?: () => Effect.Effect<void, unknown>;
 }
 export interface RunningProgram<Model, Message> extends Program<Model, Message> {
+    /** Wait for interrupted work and its finalizers as well as admitted work. */
+    readonly awaitStopped: () => Effect.Effect<void>;
+    readonly close: () => Effect.Effect<void>;
     readonly activeSlots: () => readonly CommandSlot[];
-    readonly awaitIdle: (slot?: CommandSlot) => Promise<void>;
+    readonly awaitIdle: (slot?: CommandSlot) => Effect.Effect<void>;
 }
 export declare function program<Model, Message>(options: {
     initial: Model | Snapshot<Model>;

package/dist/program.js

@@ -1,9 +1,12 @@
 import { protectSnapshot } from './snapshot.js';
 import { reportError, reportSafely } from './errors.js';
 import { traceProgram, nextProgramId, hasProgramObservers } from './diagnostics.js';
-import { Cause, Effect, Fiber, Option, Stream } from 'effect';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Option from 'effect/Option';
+import * as Stream from 'effect/Stream';
 export const commandSlot = (name) => Symbol(name);
-const taskPolicies = ['replace', 'drop', 'parallel', 'queue', 'latest-queued'];
 /** A lazy request settles successes, typed failures and defects through one message contract. */
 export function effectCommand(slot, load, handlers) {
     return {
@@ -23,6 +26,15 @@ export function mapCommand(command, map) {
         ? { ...command, stream: command.stream.pipe(Stream.map(map)) }
         : { ...command, effect: command.effect.pipe(Effect.map(map)) };
 }
+export function mapTransition(transition, maps) {
+    return {
+        model: maps.model(transition.model),
+        ...(transition.cancel ? { cancel: transition.cancel } : {}),
+        ...(transition.commands
+            ? { commands: transition.commands.map((command) => mapCommand(command, maps.message)) }
+            : {}),
+    };
+}
 export function program(options) {
     const id = nextProgramId();
     const trace = (kind, slot, message) => hasProgramObservers() &&
@@ -40,6 +52,7 @@ export function program(options) {
         });
     const waiters = new Set();
     const notify = () => {
+        notifyStopped();
         for (const waiter of waiters) {
             if (disposed ||
                 (!draining && (waiter.slot ? !running.has(waiter.slot) : running.size === 0))) {
@@ -53,11 +66,40 @@ export function program(options) {
     let current = protectSnapshot(options.initial);
     const listeners = new Set();
     const running = new Map();
+    const live = new Set();
+    const stopped = new Set();
+    const notifyStopped = () => {
+        if (live.size || running.size || draining)
+            return;
+        const completed = [...stopped];
+        stopped.clear();
+        for (const done of completed)
+            done();
+    };
+    const awaitStopped = () => Effect.callback((resume) => {
+        if (live.size === 0 && running.size === 0 && !draining)
+            return resume(Effect.void);
+        const done = () => resume(Effect.void);
+        stopped.add(done);
+        return Effect.sync(() => {
+            stopped.delete(done);
+        });
+    });
     let disposed = false;
     let draining = false;
     const queue = [];
     const deferred = [];
-    const cancel = (slot) => {
+    const discard = (command, reason) => {
+        if (command.onDiscard) {
+            try {
+                command.onDiscard(reason);
+            }
+            catch (error) {
+                reportSafely(options.onDefect ?? reportError, error);
+            }
+        }
+    };
+    const cancel = (slot, reason = 'Cancelled') => {
         // A synchronous Effect can enqueue completion behind a reset/replacement message.
         // Its fiber is already done, but cancellation still owns that unpublished completion.
         for (let index = queue.length - 1; index >= 0; index--)
@@ -67,10 +109,15 @@ export function program(options) {
         running.delete(slot);
         if (previous) {
             trace('cancel', slot);
-            previous.pending.length = 0;
-            for (const task of previous.active)
+            const pending = previous.pending.splice(0);
+            for (const command of pending)
+                discard(command, reason);
+            for (const task of previous.active) {
                 if (task.fiber)
                     Effect.runFork(Fiber.interrupt(task.fiber));
+                else if (task.command && !live.has(task))
+                    discard(task.command, reason);
+            }
             previous.active.clear();
         }
     };
@@ -104,15 +151,17 @@ export function program(options) {
             : command.action
                 ? command.action.pipe(Effect.as(Option.none()))
                 : command.effect.pipe(Effect.map(Option.some));
+        live.add(task);
         const fiber = Effect.runFork(effect);
         task.fiber = fiber;
-        if (!valid()) {
-            Effect.runFork(Fiber.interrupt(fiber));
-            return;
-        }
         fiber.addObserver((exit) => {
-            if (!valid())
+            live.delete(task);
+            if (!valid()) {
+                if (exit._tag === 'Failure' && !Cause.hasInterruptsOnly(exit.cause))
+                    reportSafely(options.onDefect ?? reportError, exit.cause);
+                notifyStopped();
                 return;
+            }
             group.active.delete(task);
             if (!group.active.size && !group.pending.length)
                 running.delete(command.slot);
@@ -133,6 +182,8 @@ export function program(options) {
             }
             notify();
         });
+        if (!valid())
+            Effect.runFork(Fiber.interrupt(fiber));
     };
     const advance = (slot, group) => {
         if (disposed || running.get(slot) !== group || group.active.size)
@@ -140,7 +191,7 @@ export function program(options) {
         const next = group.pending.shift();
         if (!next)
             return;
-        const task = {};
+        const task = { command: next };
         group.active.add(task);
         launch(next, group, task);
     };
@@ -160,10 +211,6 @@ export function program(options) {
                 }
                 const { message } = queue.shift();
                 const transition = options.update(current, message);
-                for (const command of transition.commands ?? []) {
-                    if (typeof command.slot !== 'symbol' || !taskPolicies.includes(command.policy))
-                        throw new TypeError('Commands require a commandSlot() token and an explicit concurrency policy.');
-                }
                 trace('update', undefined, message);
                 for (const slot of transition.cancel ?? [])
                     cancel(slot);
@@ -181,15 +228,18 @@ export function program(options) {
                         break;
                     const policy = command.policy;
                     let group = running.get(command.slot);
-                    if (policy === 'drop' && group)
+                    if (policy === 'drop' && group) {
+                        discard(command, 'Dropped');
                         continue;
+                    }
                     if (policy === 'replace') {
-                        cancel(command.slot);
+                        cancel(command.slot, 'Superseded');
                         group = undefined;
                     }
                     if (group && (policy === 'queue' || policy === 'latest-queued')) {
                         if (policy === 'latest-queued')
-                            group.pending.length = 0;
+                            for (const pending of group.pending.splice(0))
+                                discard(pending, 'Superseded');
                         group.pending.push(command);
                         continue;
                     }
@@ -197,7 +247,7 @@ export function program(options) {
                         group = { active: new Set(), pending: [] };
                         running.set(command.slot, group);
                     }
-                    const task = {};
+                    const task = { command };
                     group.active.add(task);
                     const admitted = group;
                     starts.push(() => launch(command, admitted, task));
@@ -221,14 +271,35 @@ export function program(options) {
         }
     };
     const send = (message) => enqueue(message);
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        queue.length = 0;
+        deferred.length = 0;
+        for (const slot of running.keys())
+            cancel(slot);
+        listeners.clear();
+        trace('dispose');
+        notify();
+    };
     return {
+        awaitStopped,
+        close: () => Effect.suspend(() => {
+            dispose();
+            return awaitStopped();
+        }),
         model: () => current,
         activeSlots: () => [...running.keys()],
-        awaitIdle: (slot) => disposed || (!draining && (slot ? !running.has(slot) : running.size === 0))
-            ? Promise.resolve()
-            : new Promise((done) => {
-                waiters.add({ slot, done });
-            }),
+        awaitIdle: (slot) => Effect.callback((resume) => {
+            if (disposed || (!draining && (slot ? !running.has(slot) : running.size === 0)))
+                return resume(Effect.void);
+            const waiter = { slot, done: () => resume(Effect.void) };
+            waiters.add(waiter);
+            return Effect.sync(() => {
+                waiters.delete(waiter);
+            });
+        }),
         send,
         subscribe(listener) {
             if (disposed)
@@ -246,17 +317,6 @@ export function program(options) {
                 listeners.delete(receive);
             };
         },
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            queue.length = 0;
-            deferred.length = 0;
-            for (const slot of running.keys())
-                cancel(slot);
-            listeners.clear();
-            trace('dispose');
-            notify();
-        },
+        dispose,
     };
 }

package/dist/query-internals.d.ts

@@ -1,9 +1,11 @@
-import type { Effect } from 'effect';
+import type * as Effect from 'effect/Effect';
 import type { Snapshot } from './snapshot.js';
-import type { Query } from './query.js';
+import type { Query, QueryGroup } from './query.js';
 export interface QueryDefinition<Args, A, E, R> {
     readonly name: string;
-    readonly load: (args: Snapshot<Args>) => Effect.Effect<A, E, R>;
+    readonly load: (args: Snapshot<Args>, previous?: Snapshot<A>) => Effect.Effect<A, E, R>;
+    readonly groups?: readonly QueryGroup[];
+    readonly unused?: 'retain' | 'cancel';
     readonly staleTime: number;
     readonly share?: (previous: Snapshot<A>, next: A | Snapshot<A>) => A | Snapshot<A>;
 }

package/dist/query.d.ts

@@ -1,4 +1,4 @@
-import type { Effect } from 'effect';
+import type * as Effect from 'effect/Effect';
 import { type QueryDefinition } from './query-internals.js';
 /** Canonical data identity: plain objects, dense arrays, and finite scalar values. */
 export type QueryKey = string | number | boolean | null | undefined | readonly QueryKey[] | {
@@ -27,4 +27,10 @@ export declare function query<Args, A, E = never, R = never>(definition: Definit
 export declare function query<A, E = never, R = never>(definition: Definition<true, A, E, R> & {
     readonly load: () => Effect.Effect<A, E, R>;
 }): Query<true, A, E, R>;
+declare const groupType: unique symbol;
+export type QueryGroup = symbol & {
+    readonly [groupType]: true;
+};
+/** Invalidation identity; equal diagnostic names do not share membership. */
+export declare const queryGroup: (name: string) => QueryGroup;
 export {};

package/dist/query.js

@@ -54,12 +54,16 @@ export function encodeQueryKey(key) {
     return encode(key);
 }
 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.');
     const result = Object.freeze({ name: definition.name });
-    registerQuery(result, Object.freeze({ ...definition, staleTime }));
+    registerQuery(result, Object.freeze({
+        ...definition,
+        ...(definition.groups ? { groups: Object.freeze([...definition.groups]) } : {}),
+        staleTime,
+    }));
     return result;
 }
+/** Invalidation identity; equal diagnostic names do not share membership. */
+export const queryGroup = (name) => Symbol(name);