@getaster/data 0.0.0-stage → 0.1.0-preview.1

package/dist/collection/grouping.d.ts

@@ -0,0 +1,75 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { Query } from "../criteria/ast.ts";
+import { type Aggregate } from "../criteria/compile.ts";
+import type { Schema, Value } from "../schema/model.ts";
+import type { KeyText } from "../store/keys.ts";
+import type { Collection } from "./collection.ts";
+import type { Groups, GroupRow } from "./groups.ts";
+export interface GroupingOptions {
+    /** Leaf collection page size, default 100. */
+    readonly pageSize?: number;
+    /** Pages retained per open leaf, default 20. */
+    readonly keepPages?: number;
+}
+/** A group header in the visible hierarchy. IDs are opaque and local to this grouping. */
+export interface GroupingHeader {
+    readonly kind: "group";
+    readonly id: string;
+    readonly parent: string | undefined;
+    readonly path: readonly Value[];
+    readonly field: string;
+    readonly level: number;
+    readonly position: number;
+    readonly siblings: number;
+    readonly group: GroupRow;
+    readonly expanded: boolean;
+    readonly loading: boolean;
+    readonly error: unknown;
+    readonly totalsAvailable: boolean;
+}
+/** A record or unloaded record position beneath a final-level group. */
+export interface GroupingRecord {
+    readonly kind: "row";
+    readonly key: KeyText | undefined;
+    readonly parent: string;
+    readonly level: number;
+    readonly position: number;
+    readonly siblings: number;
+    readonly collection: Collection;
+    readonly local: number;
+}
+export type GroupingRow = GroupingHeader | GroupingRecord;
+interface GroupingContext {
+    readonly schema: Schema;
+    readonly now: () => number;
+    groups(query: ReadonlySignal<Query>, field: string, aggregates: readonly Aggregate[]): Groups;
+    collection(query: ReadonlySignal<Query>, options: GroupingOptions): Collection;
+    release(collection: Collection): void;
+}
+/** Lazy server grouping: one grouped query per open intermediate branch, paged records at leaves. */
+export declare class Grouping {
+    #private;
+    readonly fields: readonly string[];
+    /** Open headers; collapsing a branch closes and releases its descendants. */
+    readonly open: ReadonlySignal<ReadonlySet<string>>;
+    /** Flattened visible headers and record positions, including unloaded placeholders. */
+    readonly rows: ReadonlySignal<readonly GroupingRow[]>;
+    /** Exact record count across root groups, undefined until their first answer. */
+    readonly total: ReadonlySignal<number | undefined>;
+    constructor(ctx: GroupingContext, query: Query | ReadonlySignal<Query>, fields: readonly string[], aggregates?: readonly Aggregate[], options?: GroupingOptions);
+    /** The root grouped query, including loading/error signals and refresh. */
+    get root(): Groups;
+    /** Opens a visible group. Only a final-level group requests record pages. */
+    expand(id: string): Promise<void>;
+    /** Releases this branch and all open descendants, including their query subscriptions. */
+    collapse(id: string): void;
+    /** Opens or collapses a visible group. */
+    toggle(id: string): Promise<void>;
+    /** Retries a branch's group list or visible leaf pages; omit the ID to retry root groups. */
+    retry(id?: string): Promise<void>;
+    /** Recounts changed aggregate specifications without closing open paths or leaf collections. */
+    setAggregates(aggregates: readonly Aggregate[]): void;
+    /** Stops all grouped queries and releases open leaf collections. */
+    dispose(): void;
+}
+export {};

package/dist/collection/grouping.js

@@ -0,0 +1,190 @@
+import { batch, computed, effect, signal, untracked } from "@preact/signals-core";
+import { toApply } from "../criteria/compile.js";
+import { relatedOf, resolveRelative } from "../criteria/relative.js";
+/** Lazy server grouping: one grouped query per open intermediate branch, paged records at leaves. */
+export class Grouping {
+    fields;
+    #ctx;
+    #query;
+    #options;
+    #root = signal(undefined);
+    #open = signal(new Set());
+    #version = signal(0);
+    #branches = new Map();
+    #stop;
+    #aggregates;
+    #disposed = false;
+    /** Open headers; collapsing a branch closes and releases its descendants. */
+    open = this.#open;
+    /** Flattened visible headers and record positions, including unloaded placeholders. */
+    rows;
+    /** Exact record count across root groups, undefined until their first answer. */
+    total;
+    constructor(ctx, query, fields, aggregates = [], options = {}) {
+        if (!fields.length || new Set(fields).size !== fields.length || fields.some((f) => !f))
+            throw new Error("Grouping needs distinct nonempty fields");
+        this.#ctx = ctx;
+        this.fields = [...fields];
+        this.#query = "set" in query ? signal(query) : query;
+        this.#options = { ...options };
+        this.#aggregates = aggregates.map((a) => ({ ...a }));
+        this.#validate(this.#aggregates);
+        this.#root.value = this.#groups([]);
+        this.rows = computed(() => {
+            this.#version.value;
+            const rows = [];
+            this.#append(this.root, [], rows);
+            return rows;
+        });
+        this.total = computed(() => this.root.rows.value?.reduce((sum, row) => sum + row.count, 0));
+        this.#stop = effect(() => {
+            this.#version.value;
+            const gone = [];
+            for (const [id, branch] of this.#branches) {
+                const parent = branch.path.length === 1 ? this.root : this.#branches.get(idOf(branch.path.slice(0, -1)))?.groups;
+                const rows = parent?.rows.value;
+                if (!parent || (rows && !rows.some((r) => idOf([...branch.path.slice(0, -1), r.value]) === id)))
+                    gone.push(id);
+            }
+            if (gone.length)
+                untracked(() => batch(() => { for (const id of gone)
+                    this.collapse(id); }));
+        });
+    }
+    /** The root grouped query, including loading/error signals and refresh. */
+    get root() { return this.#root.value; }
+    /** Opens a visible group. Only a final-level group requests record pages. */
+    async expand(id) {
+        if (this.#disposed || this.#open.peek().has(id))
+            return;
+        const row = this.rows.peek().find((r) => r.kind === "group" && r.id === id);
+        if (!row)
+            return;
+        const branch = { path: row.path };
+        if (row.path.length < this.fields.length)
+            branch.groups = this.#groups(row.path);
+        else
+            branch.collection = this.#ctx.collection(computed(() => this.#scoped(row.path)), this.#options);
+        batch(() => {
+            this.#branches.set(id, branch);
+            this.#open.value = new Set([...this.#open.peek(), id]);
+            this.#version.value++;
+        });
+        if (branch.collection)
+            await branch.collection.ensure(0, 1);
+    }
+    /** Releases this branch and all open descendants, including their query subscriptions. */
+    collapse(id) {
+        const branch = this.#branches.get(id);
+        if (!branch)
+            return;
+        const next = new Set(this.#open.peek());
+        for (const [key, child] of this.#branches) {
+            if (!isWithin(child.path, branch.path))
+                continue;
+            child.groups?.dispose();
+            if (child.collection)
+                this.#ctx.release(child.collection);
+            this.#branches.delete(key);
+            next.delete(key);
+        }
+        batch(() => { this.#open.value = next; this.#version.value++; });
+    }
+    /** Opens or collapses a visible group. */
+    async toggle(id) {
+        if (this.#open.peek().has(id))
+            this.collapse(id);
+        else
+            await this.expand(id);
+    }
+    /** Retries a branch's group list or visible leaf pages; omit the ID to retry root groups. */
+    async retry(id) {
+        if (this.#disposed)
+            return;
+        if (id === undefined)
+            return this.root.refresh();
+        const branch = this.#branches.get(id);
+        if (branch?.groups)
+            await branch.groups.refresh();
+        else if (branch?.collection)
+            await branch.collection.refresh();
+    }
+    /** Recounts changed aggregate specifications without closing open paths or leaf collections. */
+    setAggregates(aggregates) {
+        if (this.#disposed || JSON.stringify(aggregates) === JSON.stringify(this.#aggregates))
+            return;
+        this.#validate(aggregates);
+        this.#aggregates = aggregates.map((a) => ({ ...a }));
+        batch(() => {
+            this.root.dispose();
+            this.#root.value = this.#groups([]);
+            for (const branch of this.#branches.values()) {
+                if (!branch.groups)
+                    continue;
+                branch.groups.dispose();
+                branch.groups = this.#groups(branch.path);
+            }
+            this.#version.value++;
+        });
+    }
+    /** Stops all grouped queries and releases open leaf collections. */
+    dispose() {
+        this.#disposed = true;
+        this.#stop();
+        this.root.dispose();
+        for (const branch of this.#branches.values()) {
+            branch.groups?.dispose();
+            if (branch.collection)
+                this.#ctx.release(branch.collection);
+        }
+        this.#branches.clear();
+    }
+    #validate(aggregates) {
+        const q = this.#query.peek();
+        const set = this.#ctx.schema.set(q.set);
+        const filter = q.filter ? resolveRelative(q.filter, set.type, this.#ctx.now(), relatedOf(this.#ctx.schema, set.type)) : undefined;
+        toApply(set.type, filter, this.fields, aggregates, set, this.#ctx.schema);
+    }
+    #scoped(path) {
+        const q = this.#query.value;
+        const criteria = path.map((value, i) => ({ op: "eq", field: this.fields[i], value }));
+        if (q.filter)
+            criteria.unshift(q.filter);
+        return { ...q, ...(criteria.length ? { filter: { op: "and", args: criteria } } : {}) };
+    }
+    #groups(path) {
+        return this.#ctx.groups(computed(() => this.#scoped(path)), this.fields[path.length], this.#aggregates);
+    }
+    #append(groups, path, out) {
+        const rows = groups.rows.value;
+        if (!rows)
+            return;
+        const expanded = this.#open.value;
+        for (const [index, group] of rows.entries()) {
+            const childPath = [...path, group.value];
+            const id = idOf(childPath);
+            const branch = this.#branches.get(id);
+            const collection = branch?.collection;
+            const loading = branch?.groups?.status.value === "loading" || collection?.status.value === "loading";
+            out.push({ kind: "group", id, parent: path.length ? idOf(path) : undefined, path: childPath,
+                field: this.fields[path.length], level: childPath.length, position: index + 1, siblings: rows.length,
+                group, expanded: expanded.has(id), loading, error: branch?.groups?.error.value ?? collection?.error.value,
+                totalsAvailable: groups.status.value === "idle" });
+            if (!expanded.has(id))
+                continue;
+            if (branch?.groups)
+                this.#append(branch.groups, childPath, out);
+            else if (collection) {
+                const keys = collection.keys.value;
+                const count = collection.counted.value ? collection.count.value ?? group.count : group.count;
+                for (let i = 0; i < count; i++)
+                    out.push({ kind: "row", key: keys[i], parent: id, level: childPath.length + 1,
+                        position: i + 1, siblings: count, collection, local: i });
+            }
+        }
+    }
+}
+function idOf(path) { return `g:${JSON.stringify(path)}`; }
+function isWithin(path, prefix) {
+    return path.length >= prefix.length && idOf(path.slice(0, prefix.length)) === idOf(prefix);
+}

package/dist/collection/groups.d.ts

@@ -0,0 +1,31 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { Query } from "../criteria/ast.ts";
+import type { Aggregate } from "../criteria/compile.ts";
+import type { ODataSource } from "../odata/source.ts";
+import type { Value } from "../schema/model.ts";
+import type { RecordStore } from "../store/store.ts";
+export interface GroupRow {
+    /** The group's value; null is a group of its own. */
+    readonly value: Value;
+    readonly count: number;
+    /** Each aggregate by its alias. */
+    readonly totals: Readonly<Record<string, Value>>;
+}
+/**
+ * The groups of a query by one field, with counts and aggregates, computed
+ * by the server (`$apply`) in one request. They follow the query, and any
+ * change to the set recounts them, shortly after, once per burst.
+ */
+export declare class Groups {
+    #private;
+    readonly field: string;
+    /** In the group value's order; `undefined` until the first answer. */
+    readonly rows: ReadonlySignal<readonly GroupRow[] | undefined>;
+    readonly error: ReadonlySignal<unknown>;
+    /** The state of the current grouped request. */
+    readonly status: ReadonlySignal<"loading" | "idle" | "error">;
+    constructor(store: RecordStore, source: ODataSource, query: Query | ReadonlySignal<Query>, field: string, aggregates?: readonly Aggregate[], now?: () => number);
+    get query(): Query;
+    refresh(): Promise<void>;
+    dispose(): void;
+}

package/dist/collection/groups.js

@@ -0,0 +1,117 @@
+import { batch, effect, signal, untracked } from "@preact/signals-core";
+import { sameQuery } from "../criteria/compile.js";
+import { relatedOf, resolveRelative } from "../criteria/relative.js";
+import { relatedSets } from "./collection.js";
+const RECOUNT_DELAY = 50;
+/**
+ * The groups of a query by one field, with counts and aggregates, computed
+ * by the server (`$apply`) in one request. They follow the query, and any
+ * change to the set recounts them, shortly after, once per burst.
+ */
+export class Groups {
+    field;
+    #source;
+    #aggregates;
+    #rows = signal(undefined);
+    #error = signal(undefined);
+    #status = signal("loading");
+    #stop = [];
+    #query;
+    #related;
+    #generation = 0;
+    #disposed = false;
+    #timer;
+    /** In the group value's order; `undefined` until the first answer. */
+    rows = this.#rows;
+    error = this.#error;
+    /** The state of the current grouped request. */
+    status = this.#status;
+    #now;
+    #resolved(filter) {
+        const type = this.#source.schema.set(this.#query.set).type;
+        return resolveRelative(filter, type, this.#now(), relatedOf(this.#source.schema, type));
+    }
+    constructor(store, source, query, field, aggregates = [], now = Date.now) {
+        this.#source = source;
+        this.#now = now;
+        this.field = field;
+        this.#aggregates = aggregates;
+        const follow = "set" in query ? undefined : query;
+        this.#query = follow ? follow.peek() : query;
+        this.#related = relatedSets(this.#query.filter, source.schema.set(this.#query.set).type, source.schema);
+        source.schema.set(this.#query.set).type.field(field) ?? fail(`${this.#query.set} has no field ${field}`);
+        this.#stop.push(store.subscribe((change) => {
+            if ((change.set === this.#query.set || this.#related.has(change.set)) && change.origin.kind !== "fetch")
+                this.#soon();
+        }));
+        if (follow) {
+            this.#stop.push(effect(() => {
+                const q = follow.value;
+                untracked(() => {
+                    if (sameQuery(q, this.#query))
+                        return;
+                    this.#query = q;
+                    this.#related = relatedSets(q.filter, source.schema.set(q.set).type, source.schema);
+                    this.#rows.value = undefined;
+                    void this.refresh();
+                });
+            }));
+        }
+        void this.refresh();
+    }
+    get query() {
+        return this.#query;
+    }
+    async refresh() {
+        if (this.#disposed)
+            return;
+        clearTimeout(this.#timer);
+        const generation = ++this.#generation;
+        batch(() => { this.#status.value = "loading"; this.#error.value = undefined; });
+        try {
+            const rows = await this.#source.aggregate(this.#query.set, {
+                ...(this.#query.filter ? { filter: this.#resolved(this.#query.filter) } : {}),
+                groupBy: [this.field],
+                aggregates: this.#aggregates,
+                // Groups follow the sort's direction on their field, ascending otherwise.
+                orderBy: [{ field: this.field, ...(this.#query.orderBy?.find((k) => k.field === this.field)?.descending ? { descending: true } : {}) }],
+            });
+            if (generation !== this.#generation)
+                return;
+            const previous = this.#rows.peek();
+            const byValue = new Map(previous?.map(row => [JSON.stringify(row.value), row]));
+            const result = rows.map((r) => {
+                const totals = {};
+                for (const a of this.#aggregates)
+                    totals[a.as] = r[a.as] ?? null;
+                const value = r[this.field] ?? null;
+                const count = Number(r.count ?? 0);
+                const before = byValue.get(JSON.stringify(value));
+                return before && before.count === count && JSON.stringify(before.totals) === JSON.stringify(totals)
+                    ? before : { value, count, totals };
+            });
+            const unchanged = previous?.length === result.length && result.every((row, i) => row === previous[i]);
+            batch(() => { this.#rows.value = unchanged ? previous : result; this.#status.value = "idle"; });
+        }
+        catch (e) {
+            if (generation === this.#generation)
+                batch(() => { this.#error.value = e; this.#status.value = "error"; });
+        }
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#generation++;
+        clearTimeout(this.#timer);
+        for (const stop of this.#stop.splice(0))
+            stop();
+    }
+    #soon() {
+        this.#generation++;
+        this.#status.value = "loading";
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => void this.refresh(), RECOUNT_DELAY);
+    }
+}
+function fail(message) {
+    throw new Error(message);
+}

package/dist/collection/summary.d.ts

@@ -0,0 +1,17 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { Query } from "../criteria/ast.ts";
+import { type Aggregate } from "../criteria/compile.ts";
+import type { ODataSource } from "../odata/source.ts";
+import type { Value } from "../schema/model.ts";
+import type { RecordStore } from "../store/store.ts";
+/** Exact server totals for a query, independent of loaded collection pages. */
+export declare class Summary {
+    #private;
+    readonly values: ReadonlySignal<Readonly<Record<string, Value>> | undefined>;
+    readonly status: ReadonlySignal<"loading" | "idle" | "error">;
+    readonly error: ReadonlySignal<unknown>;
+    constructor(store: RecordStore, source: ODataSource, query: Query | ReadonlySignal<Query>, aggregates?: readonly Aggregate[], now?: () => number);
+    /** Retry or recount. Errors are exposed through `error` and `status`. */
+    refresh(): Promise<void>;
+    dispose(): void;
+}

package/dist/collection/summary.js

@@ -0,0 +1,103 @@
+import { batch, effect, signal, untracked } from "@preact/signals-core";
+import { toApply } from "../criteria/compile.js";
+import { relatedOf, resolveRelative } from "../criteria/relative.js";
+import { relatedSets } from "./collection.js";
+/** Exact server totals for a query, independent of loaded collection pages. */
+export class Summary {
+    #values = signal(undefined);
+    #status = signal("loading");
+    #error = signal(undefined);
+    values = this.#values;
+    status = this.#status;
+    error = this.#error;
+    #source;
+    #aggregates;
+    #now;
+    #stop = [];
+    #query;
+    #signature;
+    #related;
+    #generation = 0;
+    #disposed = false;
+    #timer;
+    constructor(store, source, query, aggregates = [], now = Date.now) {
+        this.#source = source;
+        this.#aggregates = aggregates.map((a) => ({ ...a }));
+        this.#now = now;
+        const follow = "set" in query ? undefined : query;
+        this.#query = follow ? follow.peek() : query;
+        this.#signature = signature(this.#query);
+        this.#related = relatedSets(this.#query.filter, source.schema.set(this.#query.set).type, source.schema);
+        this.#validate();
+        this.#stop.push(store.subscribe((change) => {
+            if (change.origin.kind === "fetch" || (change.set !== this.#query.set && !this.#related.has(change.set)))
+                return;
+            this.#invalidate();
+            clearTimeout(this.#timer);
+            this.#timer = setTimeout(() => void this.refresh(), 50);
+        }));
+        if (follow)
+            this.#stop.push(effect(() => {
+                const q = follow.value;
+                untracked(() => {
+                    if (signature(q) === this.#signature)
+                        return;
+                    this.#query = q;
+                    this.#signature = signature(q);
+                    this.#related = relatedSets(q.filter, source.schema.set(q.set).type, source.schema);
+                    void this.refresh();
+                });
+            }));
+        void this.refresh();
+    }
+    /** Retry or recount. Errors are exposed through `error` and `status`. */
+    async refresh() {
+        if (this.#disposed)
+            return;
+        clearTimeout(this.#timer);
+        const generation = this.#invalidate();
+        try {
+            this.#validate();
+            const q = this.#query;
+            const type = this.#source.schema.set(q.set).type;
+            const filter = q.filter ? resolveRelative(q.filter, type, this.#now(), relatedOf(this.#source.schema, type)) : undefined;
+            const rows = await this.#source.aggregate(q.set, { ...(filter ? { filter } : {}), aggregates: this.#aggregates });
+            if (generation !== this.#generation || this.#disposed)
+                return;
+            const row = rows[0];
+            if (!row || !Number.isSafeInteger(Number(row.count)) || Number(row.count) < 0)
+                throw new Error("Summary response has no exact row count");
+            const values = { count: Number(row.count) };
+            for (const a of this.#aggregates)
+                values[a.as] = row[a.as] ?? null;
+            batch(() => { this.#values.value = values; this.#status.value = "idle"; });
+        }
+        catch (error) {
+            if (generation !== this.#generation || this.#disposed)
+                return;
+            batch(() => { this.#error.value = error; this.#status.value = "error"; });
+        }
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#generation++;
+        clearTimeout(this.#timer);
+        for (const stop of this.#stop.splice(0))
+            stop();
+    }
+    #invalidate() {
+        this.#generation++;
+        batch(() => { this.#values.value = undefined; this.#error.value = undefined; this.#status.value = "loading"; });
+        return this.#generation;
+    }
+    #validate() {
+        const set = this.#source.schema.set(this.#query.set);
+        const criteria = this.#query.filter;
+        const filter = criteria ? resolveRelative(criteria, set.type, this.#now(), relatedOf(this.#source.schema, set.type)) : undefined;
+        toApply(set.type, filter, [], this.#aggregates, set, this.#source.schema);
+    }
+}
+/** Ordering and projection cannot change aggregate membership. */
+function signature(query) {
+    return JSON.stringify([query.set, query.filter]);
+}

package/dist/composition/activity.d.ts

@@ -0,0 +1,36 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import { Lifetime } from "./lifetime.ts";
+export type InactivePolicy = "pause" | "continue";
+export interface ActivityOptions {
+    readonly parent?: SessionActivity;
+    readonly inactive?: InactivePolicy;
+    readonly active?: boolean;
+}
+export interface ActivityRun {
+    readonly signal: AbortSignal;
+    readonly refresh: boolean;
+    /** Only the current, unaborted run can mark its refreshed data fresh. */
+    readonly markFresh: () => void;
+}
+/** Logical data activity; a paused ancestor always constrains descendants. */
+export declare class SessionActivity {
+    #private;
+    readonly lifetime: Lifetime;
+    readonly active: ReadonlySignal<boolean>;
+    readonly running: ReadonlySignal<boolean>;
+    constructor(options?: ActivityOptions);
+    setActive(active: boolean): void;
+    /** Start an owned subscription or task on each resume. Release late acquisitions too.
+     * refresh is true after a pause or invalidate; successful refresh calls run.markFresh(). */
+    run(start: (run: ActivityRun) => void | (() => void) | Promise<void | (() => void)>): ActivityTask;
+    dispose(): void;
+}
+export declare class ActivityTask {
+    #private;
+    readonly lifetime: Lifetime;
+    readonly stale: ReadonlySignal<boolean>;
+    readonly error: ReadonlySignal<unknown>;
+    constructor(activity: SessionActivity, start: (run: ActivityRun) => void | (() => void) | Promise<void | (() => void)>);
+    invalidate(): void;
+    dispose(): void;
+}

package/dist/composition/activity.js

@@ -0,0 +1,60 @@
+import { computed, effect, signal, untracked } from "@preact/signals-core";
+import { Lifetime } from "./lifetime.js";
+/** Logical data activity; a paused ancestor always constrains descendants. */
+export class SessionActivity {
+    lifetime = new Lifetime();
+    #active = signal(true);
+    #disposed = signal(false);
+    active = this.#active;
+    running;
+    constructor(options = {}) {
+        this.lifetime.defer(() => { this.#disposed.value = true; });
+        this.#active.value = options.active ?? true;
+        this.running = computed(() => !this.#disposed.value && (options.parent?.running.value ?? true) && (this.#active.value || options.inactive === "continue"));
+    }
+    setActive(active) { if (!this.lifetime.disposed)
+        this.#active.value = active; }
+    /** Start an owned subscription or task on each resume. Release late acquisitions too.
+     * refresh is true after a pause or invalidate; successful refresh calls run.markFresh(). */
+    run(start) {
+        return this.lifetime.own(new ActivityTask(this, start));
+    }
+    dispose() { this.#disposed.value = true; this.lifetime.dispose(); }
+}
+export class ActivityTask {
+    #stale = signal(true);
+    #error = signal(undefined);
+    #revision = signal(0);
+    lifetime = new Lifetime();
+    stale = this.#stale;
+    error = this.#error;
+    constructor(activity, start) {
+        this.lifetime.defer(effect(() => {
+            const running = activity.running.value;
+            this.#revision.value;
+            if (!running) {
+                untracked(() => { this.#stale.value = true; });
+                return;
+            }
+            const attempt = new Lifetime();
+            untracked(() => {
+                this.#error.value = undefined;
+                Promise.resolve().then(() => {
+                    attempt.signal.throwIfAborted();
+                    return start({ signal: attempt.signal, refresh: this.#stale.peek(), markFresh: () => { if (!attempt.disposed)
+                            this.#stale.value = false; } });
+                }).then(cleanup => { if (cleanup)
+                    attempt.defer(cleanup); }).catch(error => {
+                    if (!attempt.disposed)
+                        this.#error.value = error;
+                });
+            });
+            return () => attempt.dispose();
+        }));
+    }
+    invalidate() { if (!this.lifetime.disposed) {
+        this.#stale.value = true;
+        this.#revision.value++;
+    } }
+    dispose() { this.lifetime.dispose(); }
+}

package/dist/composition/command.d.ts

@@ -0,0 +1,22 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+export interface CommandOptions<T> {
+    readonly label: string;
+    readonly enabled?: () => boolean;
+    readonly reason?: () => string | undefined;
+    readonly run: (signal: AbortSignal) => T | Promise<T>;
+}
+/** One guarded action shared by buttons, menus, shortcuts and direct callers. */
+export declare class Command<T = unknown> {
+    #private;
+    readonly label: string;
+    readonly enabled: ReadonlySignal<boolean>;
+    readonly reason: ReadonlySignal<string | undefined>;
+    readonly busy: ReadonlySignal<boolean>;
+    readonly error: ReadonlySignal<unknown>;
+    readonly result: ReadonlySignal<T | undefined>;
+    constructor(options: CommandOptions<T>);
+    /** Concurrent callers join the same invocation; unavailable actions reject. */
+    execute(): Promise<T>;
+    dispose(): void;
+}
+export declare function command<T>(options: CommandOptions<T>): Command<T>;