@earendil-works/chord 1.4.0 → 1.5.1

package/dist/state/batch.js

@@ -0,0 +1,164 @@
+// The batch (W1), one per host: a commit adopts inside it, then every watched value that changed gets one frame, then
+// the flushes it collected run (a link sends one message); Chord calls that would reenter it are refused while it runs.
+import { invalid } from "../data/internal.js";
+import { chordMetrics } from "../telemetry.js";
+/** A host's batch: the reentrancy flag, the watched sources a commit changed, and where background errors go. */
+export class Batch {
+    /** Reports a throwing watch listener's error (to the host's `onError`); what watches get as their `report`. */
+    reportListener;
+    #report;
+    #metrics;
+    /** Set while adopting, delivering or computing a derive; one flag per host. */
+    #running = false;
+    /** Set while a pure compute runs (a derive's, a registry's `compose`): nothing may change a source then. */
+    #computing = false;
+    /** The watched sources the current commit changed, each listed once by its `changed`. */
+    #changed = [];
+    /** What runs once the current commit's frames were delivered, each listed once by its `flushing`. */
+    #flushes = [];
+    /** Set while the current commit's flushes run (its links send). */
+    #sending = false;
+    /** Changes `within` deferred while the flushes sent, for the next commit. */
+    #later = [];
+    /** Changes `soon` collected for the commit on the next microtask, while one is queued. */
+    #soon;
+    constructor(report, metrics) {
+        this.#report = report;
+        this.reportListener = (error) => report({ kind: "listener_error", error });
+        this.#metrics = chordMetrics(metrics);
+    }
+    /** Whether a commit's adoption, a delivery or a derive compute runs now: a change made now lands in this batch. */
+    get running() {
+        return this.#running;
+    }
+    /** Throws `invalid/reentrant` inside the batch: `operation` may not run during adoptions or derive computes. */
+    assertOutside(operation) {
+        if (this.#running)
+            throw invalid("reentrant", `${operation} inside a commit or a derive compute`);
+    }
+    /**
+     * Throws `invalid/reentrant` inside a pure compute (a derive's, a registry's `compose`): `operation` would change a
+     * source while one is computed from it. Changes inside an adoption are fine (they land in its batch).
+     */
+    assertNotComputing(operation) {
+        if (this.#computing)
+            throw invalid("reentrant", `${operation} inside a derive compute or a compose`);
+    }
+    /** Runs the pure compute `work` (`run`, and changes refused: `assertNotComputing`); nests. */
+    compute(work) {
+        const running = this.#running;
+        const computing = this.#computing;
+        this.#running = true;
+        this.#computing = true;
+        try {
+            return work();
+        }
+        finally {
+            this.#running = running;
+            this.#computing = computing;
+        }
+    }
+    /** Runs `work` with reentrant calls refused; nests (a derive compute inside a commit). */
+    run(work) {
+        const outer = this.#running;
+        this.#running = true;
+        try {
+            return work();
+        }
+        finally {
+            this.#running = outer;
+        }
+    }
+    /**
+     * Runs one commit's adoptions, then, still synchronously, delivers a frame for every watched value they changed
+     * (watched derives recompute through their reads), then runs the flushes the deliveries listed. A delivery or flush
+     * that throws is reported; the others still run. What `within` deferred while the flushes sent runs as the next
+     * commit, right after.
+     */
+    commit(adopt, context) {
+        this.run(() => {
+            try {
+                adopt();
+                for (const source of this.#changed) {
+                    try {
+                        source.deliver(context);
+                    }
+                    catch (error) {
+                        this.#report({ kind: "delivery_failed", error });
+                    }
+                }
+                this.#sending = true;
+                for (const flush of this.#flushes) {
+                    try {
+                        flush(context);
+                    }
+                    catch (error) {
+                        this.#report({ kind: "delivery_failed", error });
+                    }
+                }
+            }
+            finally {
+                this.#sending = false;
+                this.#changed = [];
+                this.#flushes = [];
+            }
+        });
+        const later = this.#later;
+        if (later.length === 0)
+            return;
+        this.#later = [];
+        this.commit(() => {
+            for (const each of later)
+                each();
+        }, context);
+    }
+    /**
+     * Runs `adopt` inside the commit running now, which delivers what it changed; outside one, as a commit of its own;
+     * while a commit's flushes send, as the next commit (a link closing while it sends ends its holds: their departure
+     * lands in the next batch, so one commit stays one message per link and origin). For changes that happen wherever a
+     * reference binds or ends (`host.references`, `host.activity`).
+     */
+    within(adopt, context) {
+        if (this.#sending)
+            this.#later.push(adopt);
+        else if (this.#running)
+            adopt();
+        else
+            this.commit(adopt, context);
+    }
+    /**
+     * Runs `adopt` in one commit on the next microtask, together with every other `soon` until then (changes arriving
+     * outside any commit, as a followed runtime's calls off its commit step: one batch for all of them). `context` is
+     * the first one's.
+     */
+    soon(adopt, context) {
+        if (this.#soon !== undefined) {
+            this.#soon.push(adopt);
+            return;
+        }
+        const soon = [adopt];
+        this.#soon = soon;
+        queueMicrotask(() => {
+            this.#soon = undefined;
+            this.commit(() => {
+                for (const each of soon)
+                    each();
+            }, context);
+        });
+    }
+    /** Lists a watched source the current commit changed. */
+    changed(source) {
+        this.#changed.push(source);
+    }
+    /** Lists `flush` to run at the end of the current commit, after its deliveries (a link sending what they fed it). */
+    flushing(flush) {
+        this.#flushes.push(flush);
+    }
+    /**
+     * Counts one unit of derive or registry work on the host's metrics (a lazy read has no context to count through).
+     */
+    count(counter) {
+        this.#metrics.counter(counter).add(1);
+    }
+}
+//# sourceMappingURL=batch.js.map

package/dist/state/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/state/batch.ts"],"names":[],"mappings":"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","sourcesContent":["// The batch (W1), one per host: a commit adopts inside it, then every watched value that changed gets one frame, then\n// the flushes it collected run (a link sends one message); Chord calls that would reenter it are refused while it runs.\n\nimport type { TelemetryMetrics } from \"@earendil-works/pi-telemetry\";\nimport type { Context } from \"../context/index.ts\";\nimport { invalid } from \"../data/internal.ts\";\nimport { type ChordMetrics, chordMetrics } from \"../telemetry.ts\";\n\n/** What a batch reports: a watch listener that threw, or a frame delivery that threw (a derive's value is no JSON). */\nexport type BatchError =\n\t| { readonly kind: \"listener_error\"; readonly error: unknown }\n\t| { readonly kind: \"delivery_failed\"; readonly error: unknown };\n\n/** What a commit lists to get its frame delivered: a watched source it changed (JSON or native). */\nexport interface Delivered {\n\t/** Delivers this batch's frame to its watches and subscribers; called once per batch that listed it. */\n\tdeliver(context: Context): void;\n}\n\n/** A host's batch: the reentrancy flag, the watched sources a commit changed, and where background errors go. */\nexport class Batch {\n\t/** Reports a throwing watch listener's error (to the host's `onError`); what watches get as their `report`. */\n\treadonly reportListener: (error: unknown) => void;\n\treadonly #report: (error: BatchError) => void;\n\treadonly #metrics: ChordMetrics;\n\t/** Set while adopting, delivering or computing a derive; one flag per host. */\n\t#running = false;\n\t/** Set while a pure compute runs (a derive's, a registry's `compose`): nothing may change a source then. */\n\t#computing = false;\n\t/** The watched sources the current commit changed, each listed once by its `changed`. */\n\t#changed: Delivered[] = [];\n\t/** What runs once the current commit's frames were delivered, each listed once by its `flushing`. */\n\t#flushes: ((context: Context) => void)[] = [];\n\t/** Set while the current commit's flushes run (its links send). */\n\t#sending = false;\n\t/** Changes `within` deferred while the flushes sent, for the next commit. */\n\t#later: (() => void)[] = [];\n\t/** Changes `soon` collected for the commit on the next microtask, while one is queued. */\n\t#soon: (() => void)[] | undefined;\n\n\tconstructor(report: (error: BatchError) => void, metrics: TelemetryMetrics | undefined) {\n\t\tthis.#report = report;\n\t\tthis.reportListener = (error) => report({ kind: \"listener_error\", error });\n\t\tthis.#metrics = chordMetrics(metrics);\n\t}\n\n\t/** Whether a commit's adoption, a delivery or a derive compute runs now: a change made now lands in this batch. */\n\tget running(): boolean {\n\t\treturn this.#running;\n\t}\n\n\t/** Throws `invalid/reentrant` inside the batch: `operation` may not run during adoptions or derive computes. */\n\tassertOutside(operation: string): void {\n\t\tif (this.#running) throw invalid(\"reentrant\", `${operation} inside a commit or a derive compute`);\n\t}\n\n\t/**\n\t * Throws `invalid/reentrant` inside a pure compute (a derive's, a registry's `compose`): `operation` would change a\n\t * source while one is computed from it. Changes inside an adoption are fine (they land in its batch).\n\t */\n\tassertNotComputing(operation: string): void {\n\t\tif (this.#computing) throw invalid(\"reentrant\", `${operation} inside a derive compute or a compose`);\n\t}\n\n\t/** Runs the pure compute `work` (`run`, and changes refused: `assertNotComputing`); nests. */\n\tcompute<T>(work: () => T): T {\n\t\tconst running = this.#running;\n\t\tconst computing = this.#computing;\n\t\tthis.#running = true;\n\t\tthis.#computing = true;\n\t\ttry {\n\t\t\treturn work();\n\t\t} finally {\n\t\t\tthis.#running = running;\n\t\t\tthis.#computing = computing;\n\t\t}\n\t}\n\n\t/** Runs `work` with reentrant calls refused; nests (a derive compute inside a commit). */\n\trun<T>(work: () => T): T {\n\t\tconst outer = this.#running;\n\t\tthis.#running = true;\n\t\ttry {\n\t\t\treturn work();\n\t\t} finally {\n\t\t\tthis.#running = outer;\n\t\t}\n\t}\n\n\t/**\n\t * Runs one commit's adoptions, then, still synchronously, delivers a frame for every watched value they changed\n\t * (watched derives recompute through their reads), then runs the flushes the deliveries listed. A delivery or flush\n\t * that throws is reported; the others still run. What `within` deferred while the flushes sent runs as the next\n\t * commit, right after.\n\t */\n\tcommit(adopt: () => void, context: Context): void {\n\t\tthis.run(() => {\n\t\t\ttry {\n\t\t\t\tadopt();\n\t\t\t\tfor (const source of this.#changed) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tsource.deliver(context);\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tthis.#report({ kind: \"delivery_failed\", error });\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tthis.#sending = true;\n\t\t\t\tfor (const flush of this.#flushes) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tflush(context);\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\tthis.#report({ kind: \"delivery_failed\", error });\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\tthis.#sending = false;\n\t\t\t\tthis.#changed = [];\n\t\t\t\tthis.#flushes = [];\n\t\t\t}\n\t\t});\n\t\tconst later = this.#later;\n\t\tif (later.length === 0) return;\n\t\tthis.#later = [];\n\t\tthis.commit(() => {\n\t\t\tfor (const each of later) each();\n\t\t}, context);\n\t}\n\n\t/**\n\t * Runs `adopt` inside the commit running now, which delivers what it changed; outside one, as a commit of its own;\n\t * while a commit's flushes send, as the next commit (a link closing while it sends ends its holds: their departure\n\t * lands in the next batch, so one commit stays one message per link and origin). For changes that happen wherever a\n\t * reference binds or ends (`host.references`, `host.activity`).\n\t */\n\twithin(adopt: () => void, context: Context): void {\n\t\tif (this.#sending) this.#later.push(adopt);\n\t\telse if (this.#running) adopt();\n\t\telse this.commit(adopt, context);\n\t}\n\n\t/**\n\t * Runs `adopt` in one commit on the next microtask, together with every other `soon` until then (changes arriving\n\t * outside any commit, as a followed runtime's calls off its commit step: one batch for all of them). `context` is\n\t * the first one's.\n\t */\n\tsoon(adopt: () => void, context: Context): void {\n\t\tif (this.#soon !== undefined) {\n\t\t\tthis.#soon.push(adopt);\n\t\t\treturn;\n\t\t}\n\t\tconst soon = [adopt];\n\t\tthis.#soon = soon;\n\t\tqueueMicrotask(() => {\n\t\t\tthis.#soon = undefined;\n\t\t\tthis.commit(() => {\n\t\t\t\tfor (const each of soon) each();\n\t\t\t}, context);\n\t\t});\n\t}\n\n\t/** Lists a watched source the current commit changed. */\n\tchanged(source: Delivered): void {\n\t\tthis.#changed.push(source);\n\t}\n\n\t/** Lists `flush` to run at the end of the current commit, after its deliveries (a link sending what they fed it). */\n\tflushing(flush: (context: Context) => void): void {\n\t\tthis.#flushes.push(flush);\n\t}\n\n\t/**\n\t * Counts one unit of derive or registry work on the host's metrics (a lazy read has no context to count through).\n\t */\n\tcount(\n\t\tcounter:\n\t\t\t| \"chord.derive.computes\"\n\t\t\t| \"chord.derive.diffs\"\n\t\t\t| \"chord.registry.composes\"\n\t\t\t| \"chord.registry.adapts\"\n\t\t\t| \"chord.contract.adapts\",\n\t): void {\n\t\tthis.#metrics.counter(counter).add(1);\n\t}\n}\n"]}

package/dist/state/derive.d.ts

@@ -0,0 +1,52 @@
+import type { Context } from "../context/index.ts";
+import type { JsonValue } from "../json.ts";
+import type { Batch } from "./batch.ts";
+import { NativeSource } from "./native-source.ts";
+import { type Constant, type Dependent, Source, type WatchStart } from "./watchable.ts";
+/** A JSON watchable as Chord follows it (a state member, a JSON derive source): a source, or a constant. */
+export type DeriveSource = Source | Constant;
+/** What a derive reads: a JSON source or constant, or a native source (a `writable`, a registry value, `ref.state`). */
+export type DeriveInput = DeriveSource | NativeSource;
+/**
+ * A derive: `compute` over its sources' values, recomputed on read when dirty, so each compute runs at most once per
+ * batch and after its sources. A commit only marks it; the batch recomputes it only when something watched depends on
+ * it.
+ */
+export declare class Derive extends Source implements Dependent {
+    #private;
+    constructor(sources: readonly unknown[], compute: (values: readonly unknown[]) => JsonValue, batch: Batch);
+    get value(): JsonValue;
+    /** Its value, or while failed its failure and last good value (a detached derive throws). */
+    start(): WatchStart;
+    /**
+     * Starts reading its sources, as `resolve` maps the declared ones (at activation); the first read computes.
+     * `report` gets a throw of its compute, once per failure episode (a value ends it); a failing source's error is its
+     * source's to report.
+     */
+    attach(resolve: (source: unknown, index: number) => DeriveInput, report: (error: unknown) => void): void;
+    /** Its object ended: no source keeps it, its watches end `ended`, reads throw `error` (the object's). */
+    detach(error: Error): void;
+    /**
+     * A source changed: mark this derive and its dependents dirty, flags only; a failed one too, which recomputes on its
+     * next read and heals when its sources give a value it can compute. An already dirty derive has dirty dependents
+     * (every read recomputes its sources first), so marking stops there.
+     */
+    invalidate(): void;
+    /**
+     * A source's document was retired in this batch (`Source.retiredInBatch`): a watched derive's frame carries the
+     * flag, and the derives reading this one are told too.
+     */
+    sourceRetired(visited: Set<Dependent>): void;
+    /**
+     * Delivers the frame: the diff from the watches' value, a retirement even without ops (rule 21). A compute that
+     * throws gives one failure call when the watches had a value (one per failure episode), the watches stay open; a
+     * retirement waits for the next value.
+     */
+    deliver(context: Context): void;
+}
+/**
+ * Maps an array calling `f` only for object elements not seen before (by identity), returning the previous result for
+ * the others; primitive elements are mapped every time. The cache is weak: dropped elements take their results along.
+ */
+export declare function mapShared<E, R extends JsonValue>(f: (element: E) => R): (elements: readonly E[]) => R[];
+//# sourceMappingURL=derive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/state/derive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAa,MAAM,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEnG,4GAA4G;AAC5G,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C,wHAAwH;AACxH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAoBtD;;;;GAIG;AACH,qBAAa,MAAO,SAAQ,MAAO,YAAW,SAAS;;IAgBtD,YAAY,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,EAAE,KAAK,EAIxG;IAED,IAAI,KAAK,IAAI,SAAS,CAKrB;IAED,6FAA6F;IAC7F,KAAK,IAAI,UAAU,CAOlB;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAOvG;IAED,yGAAyG;IACzG,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CASzB;IAED;;;;OAIG;IACH,UAAU,IAAI,IAAI,CAMjB;IAED;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG,IAAI,CAM3C;IAED;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmB9B;CA0BD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,EAAE,CAavG"}

package/dist/state/derive.js

@@ -0,0 +1,182 @@
+// Derives (§12): values computed from watchables, pulled when read and marked dirty by commits; and `mapShared`, which
+// keeps unchanged elements identical so a derive's diff stays cheap.
+import { diffRevisions } from "../delta/index.js";
+import { NativeSource } from "./native-source.js";
+import { handedOut, Source } from "./watchable.js";
+const DIRTY = { kind: "dirty" };
+const NO_OPS = [];
+/** What a failed derive's watches had: no value, so its next value frame replaces the value whole. */
+const NO_VALUE = Symbol("no value");
+/**
+ * A derive: `compute` over its sources' values, recomputed on read when dirty, so each compute runs at most once per
+ * batch and after its sources. A commit only marks it; the batch recomputes it only when something watched depends on
+ * it.
+ */
+export class Derive extends Source {
+    #compute;
+    /** The sources as declared, until `attach` resolves them. */
+    #declared;
+    #sources = [];
+    #state = { kind: "dirty" };
+    /** The value this derive's watches have, kept from its marking to its frame in the batch. */
+    #framed;
+    /** Whether a source's document was retired in the current batch while this derive is watched (rule 21). */
+    #retired = false;
+    /** Reports a failure of its compute to its owner (`attach`); once per failure episode, which a value ends. */
+    #report;
+    #failing = false;
+    /** Its last good value, which a watch opened while it is failed starts at (`NO_VALUE` before the first). */
+    #good = NO_VALUE;
+    constructor(sources, compute, batch) {
+        super(batch);
+        this.#declared = sources;
+        this.#compute = compute;
+    }
+    get value() {
+        const state = this.#state;
+        if (state.kind === "clean")
+            return state.value;
+        if (state.kind === "dirty")
+            return this.#recompute();
+        throw state.error;
+    }
+    /** Its value, or while failed its failure and last good value (a detached derive throws). */
+    start() {
+        try {
+            return { kind: "value", value: this.value };
+        }
+        catch (error) {
+            if (this.#state.kind !== "failed")
+                throw error;
+            return { kind: "failed", error, last: this.#good === NO_VALUE ? undefined : this.#good };
+        }
+    }
+    /**
+     * Starts reading its sources, as `resolve` maps the declared ones (at activation); the first read computes.
+     * `report` gets a throw of its compute, once per failure episode (a value ends it); a failing source's error is its
+     * source's to report.
+     */
+    attach(resolve, report) {
+        this.#report = report;
+        this.#sources = this.#declared.map(resolve);
+        this.#declared = undefined;
+        for (const source of this.#sources) {
+            if (source instanceof Source || source instanceof NativeSource)
+                source.dependents.add(this);
+        }
+    }
+    /** Its object ended: no source keeps it, its watches end `ended`, reads throw `error` (the object's). */
+    detach(error) {
+        for (const source of this.#sources) {
+            if (source instanceof Source || source instanceof NativeSource)
+                source.dependents.delete(this);
+        }
+        this.#sources = [];
+        this.#declared = undefined;
+        this.#state = { kind: "detached", error };
+        this.#framed = undefined;
+        this.endWatches();
+    }
+    /**
+     * A source changed: mark this derive and its dependents dirty, flags only; a failed one too, which recomputes on its
+     * next read and heals when its sources give a value it can compute. An already dirty derive has dirty dependents
+     * (every read recomputes its sources first), so marking stops there.
+     */
+    invalidate() {
+        const state = this.#state;
+        if (state.kind === "dirty" || state.kind === "detached")
+            return;
+        if (this.watched)
+            this.#framed = state.kind === "clean" ? state.value : NO_VALUE;
+        this.#state = DIRTY;
+        this.changed();
+    }
+    /**
+     * A source's document was retired in this batch (`Source.retiredInBatch`): a watched derive's frame carries the
+     * flag, and the derives reading this one are told too.
+     */
+    sourceRetired(visited) {
+        // Once per derive per retirement: a diamond of derives is walked in its size, not once per path.
+        if (visited.has(this))
+            return;
+        visited.add(this);
+        if (this.watched)
+            this.#retired = true;
+        for (const derive of this.dependents)
+            derive.sourceRetired(visited);
+    }
+    /**
+     * Delivers the frame: the diff from the watches' value, a retirement even without ops (rule 21). A compute that
+     * throws gives one failure call when the watches had a value (one per failure episode), the watches stay open; a
+     * retirement waits for the next value.
+     */
+    deliver(context) {
+        const before = this.#framed;
+        const retired = this.#retired;
+        this.#framed = undefined;
+        let after;
+        try {
+            after = this.value;
+        }
+        catch (error) {
+            // Still failed since the last call: nothing new for the watches.
+            if (before !== NO_VALUE)
+                this.failWatches(error, context);
+            return;
+        }
+        this.#retired = false;
+        let ops = NO_OPS;
+        if (after !== before) {
+            this.batch.count("chord.derive.diffs");
+            ops = before === NO_VALUE ? [["r", after]] : diffRevisions(before, after);
+        }
+        if (ops.length > 0 || retired)
+            this.publish(after, ops, retired, context);
+    }
+    #recompute() {
+        return this.batch.compute(() => {
+            try {
+                this.batch.count("chord.derive.computes");
+                // A failing source throws its own error here, so a derive over a failed derive fails with the same error.
+                const values = this.#sources.map((source) => source.value);
+                let value;
+                try {
+                    value = this.#compute(values);
+                }
+                catch (error) {
+                    if (!this.#failing)
+                        this.#report?.(handedOut(error));
+                    this.#failing = true;
+                    throw error;
+                }
+                this.#failing = false;
+                this.#state = { kind: "clean", value };
+                this.#good = value;
+                return value;
+            }
+            catch (error) {
+                this.#state = { kind: "failed", error };
+                throw error;
+            }
+        });
+    }
+}
+/**
+ * Maps an array calling `f` only for object elements not seen before (by identity), returning the previous result for
+ * the others; primitive elements are mapped every time. The cache is weak: dropped elements take their results along.
+ */
+export function mapShared(f) {
+    const results = new WeakMap();
+    return (elements) => elements.map((element) => {
+        // The decided rule: identity caching for objects only.
+        if (typeof element !== "object" || element === null)
+            return f(element);
+        let result = results.get(element);
+        if (result === undefined) {
+            result = f(element);
+            results.set(element, result);
+        }
+        return result;
+    });
+}
+//# sourceMappingURL=derive.js.map

package/dist/state/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../src/state/derive.ts"],"names":[],"mappings":"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","sourcesContent":["// Derives (§12): values computed from watchables, pulled when read and marked dirty by commits; and `mapShared`, which\n// keeps unchanged elements identical so a derive's diff stays cheap.\n\nimport type { Context } from \"../context/index.ts\";\nimport { diffRevisions, type Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport type { Batch } from \"./batch.ts\";\nimport { NativeSource } from \"./native-source.ts\";\nimport { type Constant, type Dependent, handedOut, Source, type WatchStart } from \"./watchable.ts\";\n\n/** A JSON watchable as Chord follows it (a state member, a JSON derive source): a source, or a constant. */\nexport type DeriveSource = Source | Constant;\n\n/** What a derive reads: a JSON source or constant, or a native source (a `writable`, a registry value, `ref.state`). */\nexport type DeriveInput = DeriveSource | NativeSource;\n\n/**\n * Where a derive stands. `dirty`: a source changed since the last compute (or there was none). A failed derive (its\n * compute threw) throws its error until a source it reads changes or is re-bound, then recomputes (self-healing, design\n * §11); a detached one (its object ended) throws its object's error for good.\n */\ntype DeriveState =\n\t| { readonly kind: \"dirty\" }\n\t| { readonly kind: \"clean\"; readonly value: JsonValue }\n\t| { readonly kind: \"failed\"; readonly error: unknown }\n\t| { readonly kind: \"detached\"; readonly error: unknown };\n\nconst DIRTY: DeriveState = { kind: \"dirty\" };\n\nconst NO_OPS: readonly Op[] = [];\n\n/** What a failed derive's watches had: no value, so its next value frame replaces the value whole. */\nconst NO_VALUE: unique symbol = Symbol(\"no value\");\n\n/**\n * A derive: `compute` over its sources' values, recomputed on read when dirty, so each compute runs at most once per\n * batch and after its sources. A commit only marks it; the batch recomputes it only when something watched depends on\n * it.\n */\nexport class Derive extends Source implements Dependent {\n\treadonly #compute: (values: readonly unknown[]) => JsonValue;\n\t/** The sources as declared, until `attach` resolves them. */\n\t#declared: readonly unknown[] | undefined;\n\t#sources: readonly DeriveInput[] = [];\n\t#state: DeriveState = { kind: \"dirty\" };\n\t/** The value this derive's watches have, kept from its marking to its frame in the batch. */\n\t#framed: JsonValue | typeof NO_VALUE | undefined;\n\t/** Whether a source's document was retired in the current batch while this derive is watched (rule 21). */\n\t#retired = false;\n\t/** Reports a failure of its compute to its owner (`attach`); once per failure episode, which a value ends. */\n\t#report: ((error: unknown) => void) | undefined;\n\t#failing = false;\n\t/** Its last good value, which a watch opened while it is failed starts at (`NO_VALUE` before the first). */\n\t#good: JsonValue | typeof NO_VALUE = NO_VALUE;\n\n\tconstructor(sources: readonly unknown[], compute: (values: readonly unknown[]) => JsonValue, batch: Batch) {\n\t\tsuper(batch);\n\t\tthis.#declared = sources;\n\t\tthis.#compute = compute;\n\t}\n\n\tget value(): JsonValue {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"clean\") return state.value;\n\t\tif (state.kind === \"dirty\") return this.#recompute();\n\t\tthrow state.error;\n\t}\n\n\t/** Its value, or while failed its failure and last good value (a detached derive throws). */\n\tstart(): WatchStart {\n\t\ttry {\n\t\t\treturn { kind: \"value\", value: this.value };\n\t\t} catch (error) {\n\t\t\tif (this.#state.kind !== \"failed\") throw error;\n\t\t\treturn { kind: \"failed\", error, last: this.#good === NO_VALUE ? undefined : this.#good };\n\t\t}\n\t}\n\n\t/**\n\t * Starts reading its sources, as `resolve` maps the declared ones (at activation); the first read computes.\n\t * `report` gets a throw of its compute, once per failure episode (a value ends it); a failing source's error is its\n\t * source's to report.\n\t */\n\tattach(resolve: (source: unknown, index: number) => DeriveInput, report: (error: unknown) => void): void {\n\t\tthis.#report = report;\n\t\tthis.#sources = this.#declared!.map(resolve);\n\t\tthis.#declared = undefined;\n\t\tfor (const source of this.#sources) {\n\t\t\tif (source instanceof Source || source instanceof NativeSource) source.dependents.add(this);\n\t\t}\n\t}\n\n\t/** Its object ended: no source keeps it, its watches end `ended`, reads throw `error` (the object's). */\n\tdetach(error: Error): void {\n\t\tfor (const source of this.#sources) {\n\t\t\tif (source instanceof Source || source instanceof NativeSource) source.dependents.delete(this);\n\t\t}\n\t\tthis.#sources = [];\n\t\tthis.#declared = undefined;\n\t\tthis.#state = { kind: \"detached\", error };\n\t\tthis.#framed = undefined;\n\t\tthis.endWatches();\n\t}\n\n\t/**\n\t * A source changed: mark this derive and its dependents dirty, flags only; a failed one too, which recomputes on its\n\t * next read and heals when its sources give a value it can compute. An already dirty derive has dirty dependents\n\t * (every read recomputes its sources first), so marking stops there.\n\t */\n\tinvalidate(): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"dirty\" || state.kind === \"detached\") return;\n\t\tif (this.watched) this.#framed = state.kind === \"clean\" ? state.value : NO_VALUE;\n\t\tthis.#state = DIRTY;\n\t\tthis.changed();\n\t}\n\n\t/**\n\t * A source's document was retired in this batch (`Source.retiredInBatch`): a watched derive's frame carries the\n\t * flag, and the derives reading this one are told too.\n\t */\n\tsourceRetired(visited: Set<Dependent>): void {\n\t\t// Once per derive per retirement: a diamond of derives is walked in its size, not once per path.\n\t\tif (visited.has(this)) return;\n\t\tvisited.add(this);\n\t\tif (this.watched) this.#retired = true;\n\t\tfor (const derive of this.dependents) derive.sourceRetired(visited);\n\t}\n\n\t/**\n\t * Delivers the frame: the diff from the watches' value, a retirement even without ops (rule 21). A compute that\n\t * throws gives one failure call when the watches had a value (one per failure episode), the watches stay open; a\n\t * retirement waits for the next value.\n\t */\n\tdeliver(context: Context): void {\n\t\tconst before = this.#framed!;\n\t\tconst retired = this.#retired;\n\t\tthis.#framed = undefined;\n\t\tlet after: JsonValue;\n\t\ttry {\n\t\t\tafter = this.value;\n\t\t} catch (error) {\n\t\t\t// Still failed since the last call: nothing new for the watches.\n\t\t\tif (before !== NO_VALUE) this.failWatches(error, context);\n\t\t\treturn;\n\t\t}\n\t\tthis.#retired = false;\n\t\tlet ops: readonly Op[] = NO_OPS;\n\t\tif (after !== before) {\n\t\t\tthis.batch.count(\"chord.derive.diffs\");\n\t\t\tops = before === NO_VALUE ? [[\"r\", after]] : diffRevisions(before, after);\n\t\t}\n\t\tif (ops.length > 0 || retired) this.publish(after, ops, retired, context);\n\t}\n\n\t#recompute(): JsonValue {\n\t\treturn this.batch.compute(() => {\n\t\t\ttry {\n\t\t\t\tthis.batch.count(\"chord.derive.computes\");\n\t\t\t\t// A failing source throws its own error here, so a derive over a failed derive fails with the same error.\n\t\t\t\tconst values = this.#sources.map((source) => source.value);\n\t\t\t\tlet value: JsonValue;\n\t\t\t\ttry {\n\t\t\t\t\tvalue = this.#compute(values);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (!this.#failing) this.#report?.(handedOut(error));\n\t\t\t\t\tthis.#failing = true;\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t\t\tthis.#failing = false;\n\t\t\t\tthis.#state = { kind: \"clean\", value };\n\t\t\t\tthis.#good = value;\n\t\t\t\treturn value;\n\t\t\t} catch (error) {\n\t\t\t\tthis.#state = { kind: \"failed\", error };\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t});\n\t}\n}\n\n/**\n * Maps an array calling `f` only for object elements not seen before (by identity), returning the previous result for\n * the others; primitive elements are mapped every time. The cache is weak: dropped elements take their results along.\n */\nexport function mapShared<E, R extends JsonValue>(f: (element: E) => R): (elements: readonly E[]) => R[] {\n\tconst results = new WeakMap<object, R>();\n\treturn (elements) =>\n\t\telements.map((element) => {\n\t\t\t// The decided rule: identity caching for objects only.\n\t\t\tif (typeof element !== \"object\" || element === null) return f(element);\n\t\t\tlet result = results.get(element);\n\t\t\tif (result === undefined) {\n\t\t\t\tresult = f(element);\n\t\t\t\tresults.set(element, result);\n\t\t\t}\n\t\t\treturn result;\n\t\t});\n}\n"]}

package/dist/state/index.d.ts

@@ -0,0 +1,6 @@
+export type { Watchable } from "../watch.ts";
+export { mapShared } from "./derive.ts";
+export type { NativeObservation, NativeObserver } from "./native-source.ts";
+export { constant } from "./watchable.ts";
+export type { Writable } from "./writable.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/state/index.js

@@ -0,0 +1,4 @@
+// State for apps: watchables, constants, writables, observers of native sources, and the derive helper `mapShared`.
+export { mapShared } from "./derive.js";
+export { constant } from "./watchable.js";
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,oHAAoH;AAGpH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// State for apps: watchables, constants, writables, observers of native sources, and the derive helper `mapShared`.\n\nexport type { Watchable } from \"../watch.ts\";\nexport { mapShared } from \"./derive.ts\";\nexport type { NativeObservation, NativeObserver } from \"./native-source.ts\";\nexport { constant } from \"./watchable.ts\";\nexport type { Writable } from \"./writable.ts\";\n"]}

package/dist/state/internal.d.ts

@@ -0,0 +1,6 @@
+export { Batch, type BatchError, type Delivered } from "./batch.ts";
+export { Derive, type DeriveInput, type DeriveSource } from "./derive.ts";
+export { FollowedSource, type NativeObservation, type NativeObserver, NativeSource, type NativeStart, } from "./native-source.ts";
+export { Constant, type Dependent, handedOut, Source, type Subscriber, type WatchStart } from "./watchable.ts";
+export { type WritableOwner, WritableSource } from "./writable.ts";
+//# sourceMappingURL=internal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/state/internal.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EACN,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,YAAY,EACZ,KAAK,WAAW,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC/G,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/state/internal.js

@@ -0,0 +1,8 @@
+// State for Chord's layers: the batch, sources (JSON and native), derives, constants and writables behind the
+// app's watchables.
+export { Batch } from "./batch.js";
+export { Derive } from "./derive.js";
+export { FollowedSource, NativeSource, } from "./native-source.js";
+export { Constant, handedOut, Source } from "./watchable.js";
+export { WritableSource } from "./writable.js";
+//# sourceMappingURL=internal.js.map

package/dist/state/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../src/state/internal.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,oBAAoB;AAEpB,OAAO,EAAE,KAAK,EAAmC,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,MAAM,EAAuC,MAAM,aAAa,CAAC;AAC1E,OAAO,EACN,cAAc,EAGd,YAAY,GAEZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAkB,SAAS,EAAE,MAAM,EAAoC,MAAM,gBAAgB,CAAC;AAC/G,OAAO,EAAsB,cAAc,EAAE,MAAM,eAAe,CAAC","sourcesContent":["// State for Chord's layers: the batch, sources (JSON and native), derives, constants and writables behind the\n// app's watchables.\n\nexport { Batch, type BatchError, type Delivered } from \"./batch.ts\";\nexport { Derive, type DeriveInput, type DeriveSource } from \"./derive.ts\";\nexport {\n\tFollowedSource,\n\ttype NativeObservation,\n\ttype NativeObserver,\n\tNativeSource,\n\ttype NativeStart,\n} from \"./native-source.ts\";\nexport { Constant, type Dependent, handedOut, Source, type Subscriber, type WatchStart } from \"./watchable.ts\";\nexport { type WritableOwner, WritableSource } from \"./writable.ts\";\n"]}

package/dist/state/native-source.d.ts

@@ -0,0 +1,106 @@
+import type { Context } from "../context/index.ts";
+import { NativeWatch, type NativeWatchable, type NativeWatchCall, type NativeWatchHandle, type WatchEnd } from "../watch.ts";
+import type { Batch } from "./batch.ts";
+import { type Dependent } from "./watchable.ts";
+/**
+ * A synchronous observer of a native source (Durable's observer shape): `advance` is called inside the batch that
+ * changed the source, so it only records; `end` once, when the source ended (`ended`) or the observer's context was
+ * aborted (`aborted`).
+ */
+export interface NativeObserver<T> {
+    /** The source's call of this batch: its new value, or a failure it may recover from. */
+    advance(call: NativeWatchCall<T>, context: Context): void;
+    /** The observer is detached for good with `end`. */
+    end(end: WatchEnd): void;
+}
+/** What `observe` gives: the value the observer starts at, and how to detach it (Durable's `Observation`). */
+export type NativeObservation<T> = {
+    readonly value: T;
+    detach(): void;
+};
+/**
+ * What a new watch of a native source starts at: its value, or while it is failed, the failure and its last good value
+ * (`last` undefined when it never had one: a watch cannot start then).
+ */
+export type NativeStart<T> = {
+    readonly kind: "value";
+    readonly value: T;
+} | {
+    readonly kind: "failed";
+    readonly error: unknown;
+    readonly last: {
+        readonly value: T;
+    } | undefined;
+};
+/**
+ * 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 declare abstract class NativeSource<T = unknown> implements NativeWatchable<T> {
+    #private;
+    /** Derives and registry tables reading this source; each removes itself when it stops. */
+    readonly dependents: Set<Dependent>;
+    /** `batch` undefined: made ended (a released reference's state). */
+    constructor(batch: Batch | undefined);
+    abstract get value(): T;
+    abstract watch(context: Context): Promise<NativeWatchHandle<T>>;
+    /** What a new watch starts at; a source that can fail and recover tells its failure. */
+    start(): NativeStart<T>;
+    /**
+     * 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(): T;
+    /** The host's batch, `undefined` once the source ended. */
+    protected get batch(): Batch | undefined;
+    /** Records a change inside the current batch: every dependent marked. */
+    protected changed(): void;
+    /** Ends the source for good: its dependents dropped, the batch let go. */
+    protected end(): void;
+}
+/**
+ * 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 declare abstract class FollowedSource<T = unknown> extends NativeSource<T> {
+    #private;
+    /** Whether a watch or an observer follows it (a registry value also while readers wait for its first value). */
+    get watched(): boolean;
+    watch(context: Context): Promise<NativeWatch<T>>;
+    /**
+     * `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: Context): NativeWatch<T>;
+    /**
+     * 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: NativeObserver<T>, context: Context): NativeObservation<T>;
+    /**
+     * 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: NativeObserver<T>): void;
+    unsubscribe(observer: NativeObserver<T>): void;
+    /** Delivers this batch's frame: the new value when the followers have another, or a failure once per episode. */
+    deliver(context: Context): void;
+    /**
+     * 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).
+     */
+    protected changed(): void;
+    /**
+     * 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).
+     */
+    protected list(): void;
+    /** Nothing follows it any more (no watch, no observer): a subclass drops what it kept for followers. */
+    protected unfollowed(): void;
+    /** Ends the source for good: watches and observers end `ended` (their abort listeners removed). */
+    protected end(): void;
+}
+//# sourceMappingURL=native-source.d.ts.map

package/dist/state/native-source.d.ts.map

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