@earendil-works/chord 1.4.0 → 1.5.1

package/dist/state/native-source.js

@@ -0,0 +1,240 @@
+// Native sources (W4, slice 8 §2): in-process values that change, compared by identity (a `writable`, a registry's
+// composed value, `ref.state`). Derives and registry tables depend on them and the batch marks them; the followed
+// ones (writables, registry values) give their watches and observers one call per batch that changed them.
+import { NativeWatch, } from "../watch.js";
+import { handedOut } from "./watchable.js";
+/**
+ * A native source as derives and registry tables read it: its value (`start()` while it may fail), the dependents a
+ * change marks (`changed()`, inside a batch), and the host's batch until it ended. How its watches get their calls is
+ * the subclass's (`FollowedSource` for writables and registry values; `ref.state` gives each state to its watches).
+ */
+export class NativeSource {
+    /** Derives and registry tables reading this source; each removes itself when it stops. */
+    dependents = new Set();
+    /** The host's batch; dropped when the source ended, so an ended source keeps no host. */
+    #batch;
+    /** `batch` undefined: made ended (a released reference's state). */
+    constructor(batch) {
+        this.#batch = batch;
+    }
+    /** What a new watch starts at; a source that can fail and recover tells its failure. */
+    start() {
+        return { kind: "value", value: this.value };
+    }
+    /**
+     * Its value now as a contribution reads it: throws its failure while it is failed, where `.value` keeps the last good
+     * value for readers (a registry whose `compose` threw).
+     */
+    current() {
+        return this.value;
+    }
+    /** The host's batch, `undefined` once the source ended. */
+    get batch() {
+        return this.#batch;
+    }
+    /** Records a change inside the current batch: every dependent marked. */
+    changed() {
+        for (const dependent of this.dependents)
+            dependent.invalidate();
+    }
+    /** Ends the source for good: its dependents dropped, the batch let go. */
+    end() {
+        this.#batch = undefined;
+        this.dependents.clear();
+    }
+}
+const ENDED = { kind: "ended" };
+const ABORTED = { kind: "aborted" };
+const FAILED = { kind: "failed" };
+const NONE = { kind: "none" };
+const NOTHING = () => { };
+/**
+ * A native source its followers get through the batch (a writable, a registry value): a change lists it for one frame
+ * when someone follows it; the frame is its value then, delivered only when it is another value (identity) than the
+ * one its followers have, or after a failure, whose call comes once per episode.
+ */
+export class FollowedSource extends NativeSource {
+    #watches = new Set();
+    /** Synchronous observers and Chord's own subscribers (`retryOn`), fed inside the batch, each with its cleanup. */
+    #observers = new Map();
+    /** What the followers have; `undefined` while nobody follows (so no old value is kept). */
+    #shown;
+    /** Listed for a frame in the current batch. */
+    #listed = false;
+    /** Whether a watch or an observer follows it (a registry value also while readers wait for its first value). */
+    get watched() {
+        return this.#watches.size > 0 || this.#observers.size > 0;
+    }
+    async watch(context) {
+        return this.openWatch(context);
+    }
+    /**
+     * `watch` without the Promise. On a failed source it opens at the last good value and its first call is the
+     * failure; with no value to start at it throws the failure. An ended source gives a watch that has ended.
+     */
+    openWatch(context) {
+        const batch = this.batch;
+        if (batch === undefined) {
+            const ended = new NativeWatch(this.value, NOTHING, NOTHING);
+            ended.end(ENDED);
+            return ended;
+        }
+        batch.assertOutside("watch");
+        const start = this.start();
+        if (start.kind === "failed" && start.last === undefined)
+            throw start.error;
+        const value = start.kind === "value" ? start.value : start.last.value;
+        this.#follow(start);
+        const watch = new NativeWatch(value, () => this.#unfollow(watch), batch.reportListener);
+        this.#watches.add(watch);
+        if (context.abortSignal !== undefined)
+            watch.observeAbort(context.abortSignal);
+        if (start.kind === "failed")
+            watch.fail(handedOut(start.error), context);
+        return watch;
+    }
+    /**
+     * Attaches a synchronous observer at the current value (Durable's `observeXXX`); it counts as following, so a lazy
+     * value is computed in the batch that changed it. Throws the failure when there is no value to start at; aborting
+     * `context` detaches it (`aborted`); the source's end detaches it too (`ended`), its abort listener removed.
+     */
+    observe(observer, context) {
+        this.batch?.assertOutside("observe");
+        const start = this.start();
+        if (start.kind === "failed" && start.last === undefined)
+            throw start.error;
+        const value = start.kind === "value" ? start.value : start.last.value;
+        if (this.batch === undefined) {
+            observer.end(ENDED);
+            return { value, detach: NOTHING };
+        }
+        const signal = context.abortSignal;
+        if (signal?.aborted) {
+            observer.end(ABORTED);
+            return { value, detach: NOTHING };
+        }
+        const aborted = () => {
+            if (!this.#observers.has(observer))
+                return;
+            this.unsubscribe(observer);
+            observer.end(ABORTED);
+        };
+        const cleanup = signal === undefined ? NOTHING : () => signal.removeEventListener("abort", aborted);
+        signal?.addEventListener("abort", aborted, { once: true });
+        this.#follow(start);
+        this.#observers.set(observer, cleanup);
+        return { value, detach: () => this.unsubscribe(observer) };
+    }
+    /**
+     * Feeds `observer` every call from now on, inside each batch, also while the source has no value (Chord's own
+     * followers: `retryOn`). Nothing is delivered for the current value.
+     */
+    subscribe(observer) {
+        if (this.batch === undefined)
+            return;
+        this.#follow(this.#startOrNone());
+        this.#observers.set(observer, NOTHING);
+    }
+    unsubscribe(observer) {
+        const cleanup = this.#observers.get(observer);
+        if (cleanup === undefined)
+            return;
+        this.#observers.delete(observer);
+        cleanup();
+        this.#settleFollowers();
+    }
+    /** Delivers this batch's frame: the new value when the followers have another, or a failure once per episode. */
+    deliver(context) {
+        this.#listed = false;
+        const shown = this.#shown;
+        if (shown === undefined)
+            return;
+        this.#deliver(shown, context);
+        // Readers waiting for a first value pulled it through this delivery: nothing is kept for them.
+        this.#settleFollowers();
+    }
+    /**
+     * Records a change inside the current batch: every dependent marked, and the source listed for a frame when someone
+     * follows it (or `watched` says so).
+     */
+    changed() {
+        super.changed();
+        this.list();
+    }
+    /**
+     * Lists the source for a frame in the current batch when someone follows it (or `watched` says so), its dependents
+     * left as they are (marked already).
+     */
+    list() {
+        if (this.#listed || !this.watched || this.batch === undefined)
+            return;
+        this.#listed = true;
+        // Only readers waiting for a first value follow it without a follower's record: they have none. Not computed
+        // here: marking runs inside adoptions, the value is pulled in the delivery.
+        this.#shown ??= NONE;
+        this.batch.changed(this);
+    }
+    /** Nothing follows it any more (no watch, no observer): a subclass drops what it kept for followers. */
+    unfollowed() { }
+    /** Ends the source for good: watches and observers end `ended` (their abort listeners removed). */
+    end() {
+        super.end();
+        this.#shown = undefined;
+        // Ending detaches, which deletes the current entry (safe while iterating) and runs no listener.
+        for (const watch of this.#watches)
+            watch.end(ENDED);
+        const observers = [...this.#observers];
+        this.#observers.clear();
+        for (const [observer, cleanup] of observers) {
+            cleanup();
+            observer.end(ENDED);
+        }
+    }
+    #deliver(shown, context) {
+        const start = this.#startOrNone();
+        if (start.kind === "failed") {
+            // A failure reaches followers that had a value: those without one wait for the first.
+            if (shown.kind !== "value")
+                return;
+            this.#shown = FAILED;
+            const error = handedOut(start.error);
+            for (const watch of this.#watches)
+                watch.fail(error, context);
+            for (const observer of [...this.#observers.keys()])
+                observer.advance({ kind: "failed", error }, context);
+            return;
+        }
+        if (start.kind !== "value" || (shown.kind === "value" && shown.value === start.value))
+            return;
+        const { value } = start;
+        this.#shown = start;
+        for (const watch of this.#watches)
+            watch.advance(value, context);
+        // A copy: an observer may detach itself in its call.
+        for (const observer of [...this.#observers.keys()])
+            observer.advance({ kind: "value", value }, context);
+    }
+    /** Its start, `none` while it has no value. */
+    #startOrNone() {
+        const start = this.start();
+        return start.kind === "failed" && start.last === undefined ? NONE : start;
+    }
+    /** A follower comes: the first one records what followers have (a later one opened at the same current value). */
+    #follow(start) {
+        if (this.#shown !== undefined)
+            return;
+        this.#shown = start.kind === "failed" ? FAILED : start;
+    }
+    #unfollow(watch) {
+        this.#watches.delete(watch);
+        this.#settleFollowers();
+    }
+    /** No follower left: nothing is shown any more, so no old value is kept. */
+    #settleFollowers() {
+        if (this.#watches.size > 0 || this.#observers.size > 0)
+            return;
+        this.#shown = undefined;
+        this.unfollowed();
+    }
+}
+//# sourceMappingURL=native-source.js.map

package/dist/state/native-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-source.js","sourceRoot":"","sources":["../../src/state/native-source.ts"],"names":[],"mappings":"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","sourcesContent":["// Native sources (W4, slice 8 §2): in-process values that change, compared by identity (a `writable`, a registry's\n// composed value, `ref.state`). Derives and registry tables depend on them and the batch marks them; the followed\n// ones (writables, registry values) give their watches and observers one call per batch that changed them.\n\nimport type { Context } from \"../context/index.ts\";\nimport {\n\tNativeWatch,\n\ttype NativeWatchable,\n\ttype NativeWatchCall,\n\ttype NativeWatchHandle,\n\ttype WatchEnd,\n} from \"../watch.ts\";\nimport type { Batch } from \"./batch.ts\";\nimport { type Dependent, handedOut } from \"./watchable.ts\";\n\n/**\n * A synchronous observer of a native source (Durable's observer shape): `advance` is called inside the batch that\n * changed the source, so it only records; `end` once, when the source ended (`ended`) or the observer's context was\n * aborted (`aborted`).\n */\nexport interface NativeObserver<T> {\n\t/** The source's call of this batch: its new value, or a failure it may recover from. */\n\tadvance(call: NativeWatchCall<T>, context: Context): void;\n\t/** The observer is detached for good with `end`. */\n\tend(end: WatchEnd): void;\n}\n\n/** What `observe` gives: the value the observer starts at, and how to detach it (Durable's `Observation`). */\nexport type NativeObservation<T> = { readonly value: T; detach(): void };\n\n/**\n * What a new watch of a native source starts at: its value, or while it is failed, the failure and its last good value\n * (`last` undefined when it never had one: a watch cannot start then).\n */\nexport type NativeStart<T> =\n\t| { readonly kind: \"value\"; readonly value: T }\n\t| { readonly kind: \"failed\"; readonly error: unknown; readonly last: { readonly value: T } | undefined };\n\n/**\n * A native source as derives and registry tables read it: its value (`start()` while it may fail), the dependents a\n * change marks (`changed()`, inside a batch), and the host's batch until it ended. How its watches get their calls is\n * the subclass's (`FollowedSource` for writables and registry values; `ref.state` gives each state to its watches).\n */\nexport abstract class NativeSource<T = unknown> implements NativeWatchable<T> {\n\t/** Derives and registry tables reading this source; each removes itself when it stops. */\n\treadonly dependents = new Set<Dependent>();\n\t/** The host's batch; dropped when the source ended, so an ended source keeps no host. */\n\t#batch: Batch | undefined;\n\n\t/** `batch` undefined: made ended (a released reference's state). */\n\tconstructor(batch: Batch | undefined) {\n\t\tthis.#batch = batch;\n\t}\n\n\tabstract get value(): T;\n\n\tabstract watch(context: Context): Promise<NativeWatchHandle<T>>;\n\n\t/** What a new watch starts at; a source that can fail and recover tells its failure. */\n\tstart(): NativeStart<T> {\n\t\treturn { kind: \"value\", value: this.value };\n\t}\n\n\t/**\n\t * Its value now as a contribution reads it: throws its failure while it is failed, where `.value` keeps the last good\n\t * value for readers (a registry whose `compose` threw).\n\t */\n\tcurrent(): T {\n\t\treturn this.value;\n\t}\n\n\t/** The host's batch, `undefined` once the source ended. */\n\tprotected get batch(): Batch | undefined {\n\t\treturn this.#batch;\n\t}\n\n\t/** Records a change inside the current batch: every dependent marked. */\n\tprotected changed(): void {\n\t\tfor (const dependent of this.dependents) dependent.invalidate();\n\t}\n\n\t/** Ends the source for good: its dependents dropped, the batch let go. */\n\tprotected end(): void {\n\t\tthis.#batch = undefined;\n\t\tthis.dependents.clear();\n\t}\n}\n\n/**\n * What the watches and observers were last given: a value, a failure (one call per failure episode), or nothing yet\n * (a source with no value, followed for its first one).\n */\ntype Shown<T> = { readonly kind: \"value\"; readonly value: T } | { readonly kind: \"failed\" } | { readonly kind: \"none\" };\n\nconst ENDED: WatchEnd = { kind: \"ended\" };\n\nconst ABORTED: WatchEnd = { kind: \"aborted\" };\n\nconst FAILED: Shown<never> = { kind: \"failed\" };\n\nconst NONE = { kind: \"none\" } as const;\n\nconst NOTHING = (): void => {};\n\n/**\n * A native source its followers get through the batch (a writable, a registry value): a change lists it for one frame\n * when someone follows it; the frame is its value then, delivered only when it is another value (identity) than the\n * one its followers have, or after a failure, whose call comes once per episode.\n */\nexport abstract class FollowedSource<T = unknown> extends NativeSource<T> {\n\treadonly #watches = new Set<NativeWatch<T>>();\n\t/** Synchronous observers and Chord's own subscribers (`retryOn`), fed inside the batch, each with its cleanup. */\n\treadonly #observers = new Map<NativeObserver<T>, () => void>();\n\t/** What the followers have; `undefined` while nobody follows (so no old value is kept). */\n\t#shown: Shown<T> | undefined;\n\t/** Listed for a frame in the current batch. */\n\t#listed = false;\n\n\t/** Whether a watch or an observer follows it (a registry value also while readers wait for its first value). */\n\tget watched(): boolean {\n\t\treturn this.#watches.size > 0 || this.#observers.size > 0;\n\t}\n\n\tasync watch(context: Context): Promise<NativeWatch<T>> {\n\t\treturn this.openWatch(context);\n\t}\n\n\t/**\n\t * `watch` without the Promise. On a failed source it opens at the last good value and its first call is the\n\t * failure; with no value to start at it throws the failure. An ended source gives a watch that has ended.\n\t */\n\topenWatch(context: Context): NativeWatch<T> {\n\t\tconst batch = this.batch;\n\t\tif (batch === undefined) {\n\t\t\tconst ended = new NativeWatch<T>(this.value, NOTHING, NOTHING);\n\t\t\tended.end(ENDED);\n\t\t\treturn ended;\n\t\t}\n\t\tbatch.assertOutside(\"watch\");\n\t\tconst start = this.start();\n\t\tif (start.kind === \"failed\" && start.last === undefined) throw start.error;\n\t\tconst value = start.kind === \"value\" ? start.value : start.last!.value;\n\t\tthis.#follow(start);\n\t\tconst watch: NativeWatch<T> = new NativeWatch(value, () => this.#unfollow(watch), batch.reportListener);\n\t\tthis.#watches.add(watch);\n\t\tif (context.abortSignal !== undefined) watch.observeAbort(context.abortSignal);\n\t\tif (start.kind === \"failed\") watch.fail(handedOut(start.error), context);\n\t\treturn watch;\n\t}\n\n\t/**\n\t * Attaches a synchronous observer at the current value (Durable's `observeXXX`); it counts as following, so a lazy\n\t * value is computed in the batch that changed it. Throws the failure when there is no value to start at; aborting\n\t * `context` detaches it (`aborted`); the source's end detaches it too (`ended`), its abort listener removed.\n\t */\n\tobserve(observer: NativeObserver<T>, context: Context): NativeObservation<T> {\n\t\tthis.batch?.assertOutside(\"observe\");\n\t\tconst start = this.start();\n\t\tif (start.kind === \"failed\" && start.last === undefined) throw start.error;\n\t\tconst value = start.kind === \"value\" ? start.value : start.last!.value;\n\t\tif (this.batch === undefined) {\n\t\t\tobserver.end(ENDED);\n\t\t\treturn { value, detach: NOTHING };\n\t\t}\n\t\tconst signal = context.abortSignal;\n\t\tif (signal?.aborted) {\n\t\t\tobserver.end(ABORTED);\n\t\t\treturn { value, detach: NOTHING };\n\t\t}\n\t\tconst aborted = (): void => {\n\t\t\tif (!this.#observers.has(observer)) return;\n\t\t\tthis.unsubscribe(observer);\n\t\t\tobserver.end(ABORTED);\n\t\t};\n\t\tconst cleanup = signal === undefined ? NOTHING : () => signal.removeEventListener(\"abort\", aborted);\n\t\tsignal?.addEventListener(\"abort\", aborted, { once: true });\n\t\tthis.#follow(start);\n\t\tthis.#observers.set(observer, cleanup);\n\t\treturn { value, detach: () => this.unsubscribe(observer) };\n\t}\n\n\t/**\n\t * Feeds `observer` every call from now on, inside each batch, also while the source has no value (Chord's own\n\t * followers: `retryOn`). Nothing is delivered for the current value.\n\t */\n\tsubscribe(observer: NativeObserver<T>): void {\n\t\tif (this.batch === undefined) return;\n\t\tthis.#follow(this.#startOrNone());\n\t\tthis.#observers.set(observer, NOTHING);\n\t}\n\n\tunsubscribe(observer: NativeObserver<T>): void {\n\t\tconst cleanup = this.#observers.get(observer);\n\t\tif (cleanup === undefined) return;\n\t\tthis.#observers.delete(observer);\n\t\tcleanup();\n\t\tthis.#settleFollowers();\n\t}\n\n\t/** Delivers this batch's frame: the new value when the followers have another, or a failure once per episode. */\n\tdeliver(context: Context): void {\n\t\tthis.#listed = false;\n\t\tconst shown = this.#shown;\n\t\tif (shown === undefined) return;\n\t\tthis.#deliver(shown, context);\n\t\t// Readers waiting for a first value pulled it through this delivery: nothing is kept for them.\n\t\tthis.#settleFollowers();\n\t}\n\n\t/**\n\t * Records a change inside the current batch: every dependent marked, and the source listed for a frame when someone\n\t * follows it (or `watched` says so).\n\t */\n\tprotected override changed(): void {\n\t\tsuper.changed();\n\t\tthis.list();\n\t}\n\n\t/**\n\t * Lists the source for a frame in the current batch when someone follows it (or `watched` says so), its dependents\n\t * left as they are (marked already).\n\t */\n\tprotected list(): void {\n\t\tif (this.#listed || !this.watched || this.batch === undefined) return;\n\t\tthis.#listed = true;\n\t\t// Only readers waiting for a first value follow it without a follower's record: they have none. Not computed\n\t\t// here: marking runs inside adoptions, the value is pulled in the delivery.\n\t\tthis.#shown ??= NONE;\n\t\tthis.batch.changed(this);\n\t}\n\n\t/** Nothing follows it any more (no watch, no observer): a subclass drops what it kept for followers. */\n\tprotected unfollowed(): void {}\n\n\t/** Ends the source for good: watches and observers end `ended` (their abort listeners removed). */\n\tprotected override end(): void {\n\t\tsuper.end();\n\t\tthis.#shown = undefined;\n\t\t// Ending detaches, which deletes the current entry (safe while iterating) and runs no listener.\n\t\tfor (const watch of this.#watches) watch.end(ENDED);\n\t\tconst observers = [...this.#observers];\n\t\tthis.#observers.clear();\n\t\tfor (const [observer, cleanup] of observers) {\n\t\t\tcleanup();\n\t\t\tobserver.end(ENDED);\n\t\t}\n\t}\n\n\t#deliver(shown: Shown<T>, context: Context): void {\n\t\tconst start = this.#startOrNone();\n\t\tif (start.kind === \"failed\") {\n\t\t\t// A failure reaches followers that had a value: those without one wait for the first.\n\t\t\tif (shown.kind !== \"value\") return;\n\t\t\tthis.#shown = FAILED;\n\t\t\tconst error = handedOut(start.error);\n\t\t\tfor (const watch of this.#watches) watch.fail(error, context);\n\t\t\tfor (const observer of [...this.#observers.keys()]) observer.advance({ kind: \"failed\", error }, context);\n\t\t\treturn;\n\t\t}\n\t\tif (start.kind !== \"value\" || (shown.kind === \"value\" && shown.value === start.value)) return;\n\t\tconst { value } = start;\n\t\tthis.#shown = start;\n\t\tfor (const watch of this.#watches) watch.advance(value, context);\n\t\t// A copy: an observer may detach itself in its call.\n\t\tfor (const observer of [...this.#observers.keys()]) observer.advance({ kind: \"value\", value }, context);\n\t}\n\n\t/** Its start, `none` while it has no value. */\n\t#startOrNone(): NativeStart<T> | { readonly kind: \"none\" } {\n\t\tconst start = this.start();\n\t\treturn start.kind === \"failed\" && start.last === undefined ? NONE : start;\n\t}\n\n\t/** A follower comes: the first one records what followers have (a later one opened at the same current value). */\n\t#follow(start: NativeStart<T> | { readonly kind: \"none\" }): void {\n\t\tif (this.#shown !== undefined) return;\n\t\tthis.#shown = start.kind === \"failed\" ? FAILED : start;\n\t}\n\n\t#unfollow(watch: NativeWatch<T>): void {\n\t\tthis.#watches.delete(watch);\n\t\tthis.#settleFollowers();\n\t}\n\n\t/** No follower left: nothing is shown any more, so no old value is kept. */\n\t#settleFollowers(): void {\n\t\tif (this.#watches.size > 0 || this.#observers.size > 0) return;\n\t\tthis.#shown = undefined;\n\t\tthis.unfollowed();\n\t}\n}\n"]}

package/dist/state/watchable.d.ts

@@ -0,0 +1,114 @@
+import type { Context } from "../context/index.ts";
+import type { Op } from "../delta/index.ts";
+import type { JsonValue } from "../json.ts";
+import { Watch, type Watchable, type WatchCall, type WatchEnd } from "../watch.ts";
+import type { Batch } from "./batch.ts";
+/**
+ * A synchronous subscriber of a source (a hold over a link, a reference's member): fed the source's call inside the batch
+ * that made it, before the batch ends, so everything one commit changed can leave in one message. The watch's own sink
+ * shape (`Watch.advance`, `Watch.end`).
+ */
+export interface Subscriber {
+    /**
+     * The source's call of this batch, in its batch's `context`: a value (the ops from the previous one, and whether its
+     * document was retired in it, or for a derive one of its sources' documents), or a failure it may recover from; the
+     * next value after a failure is `[["r", value]]`.
+     */
+    advance(call: WatchCall<JsonValue>, context: Context): void;
+    /** The source ended for good with `end`; nothing follows, and the subscriber is dropped. */
+    end(end: WatchEnd): void;
+    /**
+     * The source ended for good after its last call (a followed runtime ended): a subscriber delivering later (a watch)
+     * ends `ended` once it delivered what it was given, others end now.
+     */
+    endAfterDelivery(): void;
+}
+/**
+ * What a new watch of a source starts at (design §11): its value, or, while it is failed, the failure and its last good
+ * value (`undefined` when it never had one: a watch cannot start then, there is nothing to start at).
+ */
+export type WatchStart = {
+    readonly kind: "value";
+    readonly value: JsonValue;
+} | {
+    readonly kind: "failed";
+    readonly error: unknown;
+    readonly last: JsonValue | undefined;
+};
+/**
+ * An error Chord hands to apps (a failure call, a report), its stack made text first: until then V8 keeps the frames'
+ * receivers, which would keep the host behind the throw alive for as long as an app keeps the error.
+ */
+export declare function handedOut<E>(error: E): E;
+/**
+ * What reads a source and is marked by its changes: a derive, or a reference's member forwarding to derives (`Source.
+ * dependents`).
+ */
+export interface Dependent {
+    /** The source changed in the current batch: flags only, no compute. */
+    invalidate(): void;
+    /** A source's document was retired in the current batch (rule 21); `visited` keeps a diamond walked once. */
+    sourceRetired(visited: Set<Dependent>): void;
+}
+/**
+ * A changing value on a host (a singleton document, a derive, a replica): its watches and subscribers get one frame
+ * per batch that changed it, and the derives reading it are marked dirty when it changes.
+ */
+export declare abstract class Source implements Watchable<JsonValue> {
+    #private;
+    /** Derives reading this source (and references' members forwarding to some); each removes itself when it stops. */
+    readonly dependents: Set<Dependent>;
+    protected readonly batch: Batch;
+    constructor(batch: Batch);
+    abstract get value(): JsonValue;
+    /** Whether a watch or a subscriber follows this source. */
+    get watched(): boolean;
+    watch(context: Context): Promise<Watch<JsonValue>>;
+    /**
+     * `watch` without the Promise, for references, which must register the watch before anything else runs. On a failed
+     * source it opens at the last good value and its first call is the failure; with no value to start at it throws the
+     * failure.
+     */
+    openWatch(context: Context): Watch<JsonValue>;
+    /** What a new watch starts at; a source that can fail and recover tells its failure (`WatchStart`). */
+    start(): WatchStart;
+    /** Feeds `subscriber` every frame from now on, inside each batch; the caller took the current value first. */
+    subscribe(subscriber: Subscriber): void;
+    unsubscribe(subscriber: Subscriber): void;
+    /** Delivers this batch's frame to its watches; called once per batch that listed it with `changed`. */
+    abstract deliver(context: Context): void;
+    /** Records a change in the current batch: listed for a frame when watched, and every dependent marked dirty. */
+    protected changed(): void;
+    /**
+     * Records a retirement of this source's document in the current batch: every derive reading it, directly or
+     * through other derives, carries the flag on in its frame (rule 21). Called after `changed`.
+     */
+    protected retiredInBatch(): void;
+    /** Queues one frame on every watch and feeds it to every subscriber. */
+    protected publish(value: JsonValue, ops: readonly Op[], retired: boolean, context: Context): void;
+    /** Queues `call` on every watch and feeds it to every subscriber, as it is (a reference's member passes one on). */
+    protected forward(call: WatchCall<JsonValue>, context: Context): void;
+    /**
+     * Gives every watch and subscriber one failure call (design §11): the source cannot compute its value now and may
+     * recover; they stay open, and its next value is `[["r", value]]`.
+     */
+    protected failWatches(error: unknown, context: Context): void;
+    /**
+     * Ends every watch and subscriber for good once what they were given is delivered (a followed runtime ended after a
+     * last call, Durable's `endAfterDelivery`): `ended`; nothing follows.
+     */
+    protected endWatchesAfterDelivery(): void;
+    /** Ends every watch and subscriber for good (its owner ended): `ended`; nothing follows. */
+    protected endWatches(): void;
+}
+/** A watchable that never changes (start data, §18); usable as a state member and as a derive source. */
+export declare function constant<const T extends JsonValue>(value: T): Watchable<T>;
+/** The watchable behind `constant(value)`: its watches never get a frame and end only by stop or cancellation. */
+export declare class Constant implements Watchable<JsonValue> {
+    readonly value: JsonValue;
+    constructor(value: JsonValue);
+    watch(context: Context): Promise<Watch<JsonValue>>;
+    /** As `Source.openWatch`; nothing is delivered, so nothing is reported. */
+    openWatch(context: Context): Watch<JsonValue>;
+}
+//# sourceMappingURL=watchable.d.ts.map

package/dist/state/watchable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchable.d.ts","sourceRoot":"","sources":["../../src/state/watchable.ts"],"names":[],"mappings":"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"}

package/dist/state/watchable.js

@@ -0,0 +1,156 @@
+// Chord's JSON watchables: sources (documents and derives, with their watches and dependent derives) and constants.
+import { Watch } from "../watch.js";
+/**
+ * An error Chord hands to apps (a failure call, a report), its stack made text first: until then V8 keeps the frames'
+ * receivers, which would keep the host behind the throw alive for as long as an app keeps the error.
+ */
+export function handedOut(error) {
+    if (error instanceof Error)
+        void error.stack;
+    return error;
+}
+const ENDED = { kind: "ended" };
+/**
+ * A changing value on a host (a singleton document, a derive, a replica): its watches and subscribers get one frame
+ * per batch that changed it, and the derives reading it are marked dirty when it changes.
+ */
+export class Source {
+    /** Derives reading this source (and references' members forwarding to some); each removes itself when it stops. */
+    dependents = new Set();
+    batch;
+    /** Its watches and subscribers, each made by its first: most sources (a reference's members) never have one. */
+    #watches;
+    #subscribers;
+    constructor(batch) {
+        this.batch = batch;
+    }
+    /** Whether a watch or a subscriber follows this source. */
+    get watched() {
+        return (this.#watches?.size ?? 0) > 0 || (this.#subscribers?.size ?? 0) > 0;
+    }
+    async watch(context) {
+        return this.openWatch(context);
+    }
+    /**
+     * `watch` without the Promise, for references, which must register the watch before anything else runs. On a failed
+     * source it opens at the last good value and its first call is the failure; with no value to start at it throws the
+     * failure.
+     */
+    openWatch(context) {
+        this.batch.assertOutside("watch");
+        const start = this.start();
+        if (start.kind === "failed" && start.last === undefined)
+            throw start.error;
+        const value = start.kind === "value" ? start.value : start.last;
+        this.#watches ??= new Set();
+        const watches = this.#watches;
+        const watch = new Watch(value, () => watches.delete(watch), this.batch.reportListener);
+        watches.add(watch);
+        if (context.abortSignal !== undefined)
+            watch.observeAbort(context.abortSignal);
+        if (start.kind === "failed")
+            watch.fail(start.error, context);
+        return watch;
+    }
+    /** What a new watch starts at; a source that can fail and recover tells its failure (`WatchStart`). */
+    start() {
+        return { kind: "value", value: this.value };
+    }
+    /** Feeds `subscriber` every frame from now on, inside each batch; the caller took the current value first. */
+    subscribe(subscriber) {
+        this.#subscribers ??= new Set();
+        this.#subscribers.add(subscriber);
+    }
+    unsubscribe(subscriber) {
+        this.#subscribers?.delete(subscriber);
+    }
+    /** Records a change in the current batch: listed for a frame when watched, and every dependent marked dirty. */
+    changed() {
+        if (this.watched)
+            this.batch.changed(this);
+        for (const derive of this.dependents)
+            derive.invalidate();
+    }
+    /**
+     * Records a retirement of this source's document in the current batch: every derive reading it, directly or
+     * through other derives, carries the flag on in its frame (rule 21). Called after `changed`.
+     */
+    retiredInBatch() {
+        // Allocated only for a retirement, which is rare.
+        const visited = new Set();
+        for (const derive of this.dependents)
+            derive.sourceRetired(visited);
+    }
+    /** Queues one frame on every watch and feeds it to every subscriber. */
+    publish(value, ops, retired, context) {
+        this.forward({ kind: "value", value, ops, retired }, context);
+    }
+    /** Queues `call` on every watch and feeds it to every subscriber, as it is (a reference's member passes one on). */
+    forward(call, context) {
+        if (this.#watches !== undefined)
+            for (const watch of this.#watches)
+                watch.advance(call, context);
+        if (this.#subscribers !== undefined)
+            for (const subscriber of this.#subscribers)
+                subscriber.advance(call, context);
+    }
+    /**
+     * Gives every watch and subscriber one failure call (design §11): the source cannot compute its value now and may
+     * recover; they stay open, and its next value is `[["r", value]]`.
+     */
+    failWatches(error, context) {
+        this.forward({ kind: "failed", error: handedOut(error) }, context);
+    }
+    /**
+     * Ends every watch and subscriber for good once what they were given is delivered (a followed runtime ended after a
+     * last call, Durable's `endAfterDelivery`): `ended`; nothing follows.
+     */
+    endWatchesAfterDelivery() {
+        if (this.#watches !== undefined)
+            for (const watch of [...this.#watches])
+                watch.endAfterDelivery();
+        if (this.#subscribers === undefined || this.#subscribers.size === 0)
+            return;
+        const subscribers = [...this.#subscribers];
+        this.#subscribers.clear();
+        for (const subscriber of subscribers)
+            subscriber.endAfterDelivery();
+    }
+    /** Ends every watch and subscriber for good (its owner ended): `ended`; nothing follows. */
+    endWatches() {
+        // Ending detaches, which deletes the current entry (safe while iterating) and runs no listener.
+        if (this.#watches !== undefined)
+            for (const watch of this.#watches)
+                watch.end(ENDED);
+        if (this.#subscribers === undefined || this.#subscribers.size === 0)
+            return;
+        // A copy: a subscriber may unsubscribe as it ends.
+        const subscribers = [...this.#subscribers];
+        this.#subscribers.clear();
+        for (const subscriber of subscribers)
+            subscriber.end(ENDED);
+    }
+}
+/** A watchable that never changes (start data, §18); usable as a state member and as a derive source. */
+export function constant(value) {
+    // The constant holds `value` as it was given.
+    return new Constant(value);
+}
+/** The watchable behind `constant(value)`: its watches never get a frame and end only by stop or cancellation. */
+export class Constant {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    async watch(context) {
+        return this.openWatch(context);
+    }
+    /** As `Source.openWatch`; nothing is delivered, so nothing is reported. */
+    openWatch(context) {
+        const watch = new Watch(this.value, () => { }, () => { });
+        if (context.abortSignal !== undefined)
+            watch.observeAbort(context.abortSignal);
+        return watch;
+    }
+}
+//# sourceMappingURL=watchable.js.map

package/dist/state/watchable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchable.js","sourceRoot":"","sources":["../../src/state/watchable.ts"],"names":[],"mappings":"AAAA,oHAAoH;AAKpH,OAAO,EAAE,KAAK,EAAiD,MAAM,aAAa,CAAC;AAgCnF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAI,KAAQ;IACpC,IAAI,KAAK,YAAY,KAAK;QAAE,KAAK,KAAK,CAAC,KAAK,CAAC;IAC7C,OAAO,KAAK,CAAC;AACd,CAAC;AAaD,MAAM,KAAK,GAAa,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAE1C;;;GAGG;AACH,MAAM,OAAgB,MAAM;IAC3B,mHAAmH;IAC1G,UAAU,GAAG,IAAI,GAAG,EAAa,CAAC;IACxB,KAAK,CAAQ;IAChC,gHAAgH;IAChH,QAAQ,CAAoC;IAC5C,YAAY,CAA8B;IAE1C,YAAY,KAAY;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAID,2DAA2D;IAC3D,IAAI,OAAO;QACV,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAgB;QAC3B,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,OAAgB;QACzB,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,KAAK,CAAC,KAAK,CAAC;QAC3E,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAK,CAAC;QACjE,IAAI,CAAC,QAAQ,KAAK,IAAI,GAAG,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,MAAM,KAAK,GAAqB,IAAI,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACzG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC/E,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,KAAK,CAAC;IACd,CAAC;IAED,uGAAuG;IACvG,KAAK;QACJ,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC7C,CAAC;IAED,8GAA8G;IAC9G,SAAS,CAAC,UAAsB;QAC/B,IAAI,CAAC,YAAY,KAAK,IAAI,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED,WAAW,CAAC,UAAsB;QACjC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAKD,gHAAgH;IACtG,OAAO;QAChB,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,UAAU;YAAE,MAAM,CAAC,UAAU,EAAE,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACO,cAAc;QACvB,kDAAkD;QAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;QACrC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,UAAU;YAAE,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACrE,CAAC;IAED,wEAAwE;IAC9D,OAAO,CAAC,KAAgB,EAAE,GAAkB,EAAE,OAAgB,EAAE,OAAgB;QACzF,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED,oHAAoH;IAC1G,OAAO,CAAC,IAA0B,EAAE,OAAgB;QAC7D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;gBAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjG,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAClC,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,YAAY;gBAAE,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED;;;OAGG;IACO,WAAW,CAAC,KAAc,EAAE,OAAgB;QACrD,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACO,uBAAuB;QAChC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAClG,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC5E,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3C,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,UAAU,IAAI,WAAW;YAAE,UAAU,CAAC,gBAAgB,EAAE,CAAC;IACrE,CAAC;IAED,4FAA4F;IAClF,UAAU;QACnB,gGAAgG;QAChG,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;gBAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrF,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAC5E,mDAAmD;QACnD,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3C,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,MAAM,UAAU,IAAI,WAAW;YAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC7D,CAAC;CACD;AAED,yGAAyG;AACzG,MAAM,UAAU,QAAQ,CAA4B,KAAQ;IAC3D,8CAA8C;IAC9C,OAAO,IAAI,QAAQ,CAAC,KAAK,CAA4B,CAAC;AACvD,CAAC;AAED,kHAAkH;AAClH,MAAM,OAAO,QAAQ;IACX,KAAK,CAAY;IAE1B,YAAY,KAAgB;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAgB;QAC3B,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,2EAA2E;IAC3E,SAAS,CAAC,OAAgB;QACzB,MAAM,KAAK,GAAG,IAAI,KAAK,CACtB,IAAI,CAAC,KAAK,EACV,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACR,CAAC;QACF,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC/E,OAAO,KAAK,CAAC;IACd,CAAC;CACD","sourcesContent":["// Chord's JSON watchables: sources (documents and derives, with their watches and dependent derives) and constants.\n\nimport type { Context } from \"../context/index.ts\";\nimport type { Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport { Watch, type Watchable, type WatchCall, type WatchEnd } from \"../watch.ts\";\nimport type { Batch } from \"./batch.ts\";\n\n/**\n * A synchronous subscriber of a source (a hold over a link, a reference's member): fed the source's call inside the batch\n * that made it, before the batch ends, so everything one commit changed can leave in one message. The watch's own sink\n * shape (`Watch.advance`, `Watch.end`).\n */\nexport interface Subscriber {\n\t/**\n\t * The source's call of this batch, in its batch's `context`: a value (the ops from the previous one, and whether its\n\t * document was retired in it, or for a derive one of its sources' documents), or a failure it may recover from; the\n\t * next value after a failure is `[[\"r\", value]]`.\n\t */\n\tadvance(call: WatchCall<JsonValue>, context: Context): void;\n\t/** The source ended for good with `end`; nothing follows, and the subscriber is dropped. */\n\tend(end: WatchEnd): void;\n\t/**\n\t * The source ended for good after its last call (a followed runtime ended): a subscriber delivering later (a watch)\n\t * ends `ended` once it delivered what it was given, others end now.\n\t */\n\tendAfterDelivery(): void;\n}\n\n/**\n * What a new watch of a source starts at (design §11): its value, or, while it is failed, the failure and its last good\n * value (`undefined` when it never had one: a watch cannot start then, there is nothing to start at).\n */\nexport type WatchStart =\n\t| { readonly kind: \"value\"; readonly value: JsonValue }\n\t| { readonly kind: \"failed\"; readonly error: unknown; readonly last: JsonValue | undefined };\n\n/**\n * An error Chord hands to apps (a failure call, a report), its stack made text first: until then V8 keeps the frames'\n * receivers, which would keep the host behind the throw alive for as long as an app keeps the error.\n */\nexport function handedOut<E>(error: E): E {\n\tif (error instanceof Error) void error.stack;\n\treturn error;\n}\n\n/**\n * What reads a source and is marked by its changes: a derive, or a reference's member forwarding to derives (`Source.\n * dependents`).\n */\nexport interface Dependent {\n\t/** The source changed in the current batch: flags only, no compute. */\n\tinvalidate(): void;\n\t/** A source's document was retired in the current batch (rule 21); `visited` keeps a diamond walked once. */\n\tsourceRetired(visited: Set<Dependent>): void;\n}\n\nconst ENDED: WatchEnd = { kind: \"ended\" };\n\n/**\n * A changing value on a host (a singleton document, a derive, a replica): its watches and subscribers get one frame\n * per batch that changed it, and the derives reading it are marked dirty when it changes.\n */\nexport abstract class Source implements Watchable<JsonValue> {\n\t/** Derives reading this source (and references' members forwarding to some); each removes itself when it stops. */\n\treadonly dependents = new Set<Dependent>();\n\tprotected readonly batch: Batch;\n\t/** Its watches and subscribers, each made by its first: most sources (a reference's members) never have one. */\n\t#watches: Set<Watch<JsonValue>> | undefined;\n\t#subscribers: Set<Subscriber> | undefined;\n\n\tconstructor(batch: Batch) {\n\t\tthis.batch = batch;\n\t}\n\n\tabstract get value(): JsonValue;\n\n\t/** Whether a watch or a subscriber follows this source. */\n\tget watched(): boolean {\n\t\treturn (this.#watches?.size ?? 0) > 0 || (this.#subscribers?.size ?? 0) > 0;\n\t}\n\n\tasync watch(context: Context): Promise<Watch<JsonValue>> {\n\t\treturn this.openWatch(context);\n\t}\n\n\t/**\n\t * `watch` without the Promise, for references, which must register the watch before anything else runs. On a failed\n\t * source it opens at the last good value and its first call is the failure; with no value to start at it throws the\n\t * failure.\n\t */\n\topenWatch(context: Context): Watch<JsonValue> {\n\t\tthis.batch.assertOutside(\"watch\");\n\t\tconst start = this.start();\n\t\tif (start.kind === \"failed\" && start.last === undefined) throw start.error;\n\t\tconst value = start.kind === \"value\" ? start.value : start.last!;\n\t\tthis.#watches ??= new Set();\n\t\tconst watches = this.#watches;\n\t\tconst watch: Watch<JsonValue> = new Watch(value, () => watches.delete(watch), this.batch.reportListener);\n\t\twatches.add(watch);\n\t\tif (context.abortSignal !== undefined) watch.observeAbort(context.abortSignal);\n\t\tif (start.kind === \"failed\") watch.fail(start.error, context);\n\t\treturn watch;\n\t}\n\n\t/** What a new watch starts at; a source that can fail and recover tells its failure (`WatchStart`). */\n\tstart(): WatchStart {\n\t\treturn { kind: \"value\", value: this.value };\n\t}\n\n\t/** Feeds `subscriber` every frame from now on, inside each batch; the caller took the current value first. */\n\tsubscribe(subscriber: Subscriber): void {\n\t\tthis.#subscribers ??= new Set();\n\t\tthis.#subscribers.add(subscriber);\n\t}\n\n\tunsubscribe(subscriber: Subscriber): void {\n\t\tthis.#subscribers?.delete(subscriber);\n\t}\n\n\t/** Delivers this batch's frame to its watches; called once per batch that listed it with `changed`. */\n\tabstract deliver(context: Context): void;\n\n\t/** Records a change in the current batch: listed for a frame when watched, and every dependent marked dirty. */\n\tprotected changed(): void {\n\t\tif (this.watched) this.batch.changed(this);\n\t\tfor (const derive of this.dependents) derive.invalidate();\n\t}\n\n\t/**\n\t * Records a retirement of this source's document in the current batch: every derive reading it, directly or\n\t * through other derives, carries the flag on in its frame (rule 21). Called after `changed`.\n\t */\n\tprotected retiredInBatch(): void {\n\t\t// Allocated only for a retirement, which is rare.\n\t\tconst visited = new Set<Dependent>();\n\t\tfor (const derive of this.dependents) derive.sourceRetired(visited);\n\t}\n\n\t/** Queues one frame on every watch and feeds it to every subscriber. */\n\tprotected publish(value: JsonValue, ops: readonly Op[], retired: boolean, context: Context): void {\n\t\tthis.forward({ kind: \"value\", value, ops, retired }, context);\n\t}\n\n\t/** Queues `call` on every watch and feeds it to every subscriber, as it is (a reference's member passes one on). */\n\tprotected forward(call: WatchCall<JsonValue>, context: Context): void {\n\t\tif (this.#watches !== undefined) for (const watch of this.#watches) watch.advance(call, context);\n\t\tif (this.#subscribers !== undefined)\n\t\t\tfor (const subscriber of this.#subscribers) subscriber.advance(call, context);\n\t}\n\n\t/**\n\t * Gives every watch and subscriber one failure call (design §11): the source cannot compute its value now and may\n\t * recover; they stay open, and its next value is `[[\"r\", value]]`.\n\t */\n\tprotected failWatches(error: unknown, context: Context): void {\n\t\tthis.forward({ kind: \"failed\", error: handedOut(error) }, context);\n\t}\n\n\t/**\n\t * Ends every watch and subscriber for good once what they were given is delivered (a followed runtime ended after a\n\t * last call, Durable's `endAfterDelivery`): `ended`; nothing follows.\n\t */\n\tprotected endWatchesAfterDelivery(): void {\n\t\tif (this.#watches !== undefined) for (const watch of [...this.#watches]) watch.endAfterDelivery();\n\t\tif (this.#subscribers === undefined || this.#subscribers.size === 0) return;\n\t\tconst subscribers = [...this.#subscribers];\n\t\tthis.#subscribers.clear();\n\t\tfor (const subscriber of subscribers) subscriber.endAfterDelivery();\n\t}\n\n\t/** Ends every watch and subscriber for good (its owner ended): `ended`; nothing follows. */\n\tprotected endWatches(): void {\n\t\t// Ending detaches, which deletes the current entry (safe while iterating) and runs no listener.\n\t\tif (this.#watches !== undefined) for (const watch of this.#watches) watch.end(ENDED);\n\t\tif (this.#subscribers === undefined || this.#subscribers.size === 0) return;\n\t\t// A copy: a subscriber may unsubscribe as it ends.\n\t\tconst subscribers = [...this.#subscribers];\n\t\tthis.#subscribers.clear();\n\t\tfor (const subscriber of subscribers) subscriber.end(ENDED);\n\t}\n}\n\n/** A watchable that never changes (start data, §18); usable as a state member and as a derive source. */\nexport function constant<const T extends JsonValue>(value: T): Watchable<T> {\n\t// The constant holds `value` as it was given.\n\treturn new Constant(value) as unknown as Watchable<T>;\n}\n\n/** The watchable behind `constant(value)`: its watches never get a frame and end only by stop or cancellation. */\nexport class Constant implements Watchable<JsonValue> {\n\treadonly value: JsonValue;\n\n\tconstructor(value: JsonValue) {\n\t\tthis.value = value;\n\t}\n\n\tasync watch(context: Context): Promise<Watch<JsonValue>> {\n\t\treturn this.openWatch(context);\n\t}\n\n\t/** As `Source.openWatch`; nothing is delivered, so nothing is reported. */\n\topenWatch(context: Context): Watch<JsonValue> {\n\t\tconst watch = new Watch<JsonValue>(\n\t\t\tthis.value,\n\t\t\t() => {},\n\t\t\t() => {},\n\t\t);\n\t\tif (context.abortSignal !== undefined) watch.observeAbort(context.abortSignal);\n\t\treturn watch;\n\t}\n}\n"]}

package/dist/state/writable.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from "../context/index.ts";
+import type { NativeWatchable } from "../watch.ts";
+import type { Batch } from "./batch.ts";
+import { FollowedSource } from "./native-source.ts";
+/** An in-process value that changes when its owner sets it; `set` of the same value notifies nobody. */
+export interface Writable<T> extends NativeWatchable<T> {
+    /**
+     * Sets the value: a new value (by identity) is a new frame for its watches and marks the derives and registry
+     * tables reading it, in the batch running now or in one of its own. Throws `released` once its attempt ended, and
+     * `invalid/reentrant` inside a derive compute or a `compose`.
+     */
+    set(value: T): void;
+}
+/** Who owns a writable: the context its own batches run in, and the check that its attempt still runs. */
+export type WritableOwner = {
+    readonly context: Context;
+    /** Throws `released` once the attempt that made it was sealed. */
+    assertUsable(): void;
+};
+/** A writable: its value, set by its owner's code, delivered through the host's batch. */
+export declare class WritableSource<T> extends FollowedSource<T> implements Writable<T> {
+    #private;
+    constructor(initial: T, owner: WritableOwner, batch: Batch);
+    get value(): T;
+    set(value: T): void;
+    /**
+     * Its attempt ended with `error`: its watches end `ended`, `set` throws `error`, its value stays readable; it keeps
+     * neither its attempt nor the host.
+     */
+    detach(error: Error): void;
+}
+//# sourceMappingURL=writable.d.ts.map

package/dist/state/writable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writable.d.ts","sourceRoot":"","sources":["../../src/state/writable.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wGAAwG;AACxG,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IACtD;;;;OAIG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACpB;AAED,0GAA0G;AAC1G,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kEAAkE;IAClE,YAAY,IAAI,IAAI,CAAC;CACrB,CAAC;AAOF,0FAA0F;AAC1F,qBAAa,cAAc,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAE,YAAW,QAAQ,CAAC,CAAC,CAAC;;IAI9E,YAAY,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAIzD;IAED,IAAI,KAAK,IAAI,CAAC,CAEb;IAED,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CASlB;IAaD;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAKzB;CACD"}