@earendil-works/chord 1.4.0 → 1.5.0

package/dist/next/host/follow.js

@@ -0,0 +1,207 @@
+// Followed sources (slice 6b D9, R4, §3): `self.follow(attach)`, a Chord source over a synchronous observer of another
+// runtime (Durable's `observeConversation`, `observeTaskGraph`, `observeDoc`). Attached during its attempt's
+// activation, detached at the attempt's end. Calls inside a running batch (Durable adopting in the store's commit step)
+// are marked in that batch, calls outside one are grouped into one batch on the next microtask, so a derive over two
+// views of one commit computes once with both changes.
+import { ChordError } from "../data/index.js";
+import { Source } from "../state/internal.js";
+const NO_OPS = [];
+const ENDED = { kind: "ended" };
+/** A followed source: the runtime's value, its calls applied in order, its frames delivered in the host's batch. */
+export class FollowSource extends Source {
+    #attach;
+    #owner;
+    #state = { kind: "attaching", end: undefined };
+    #value;
+    /** Calls not applied yet: before the attachment resolved, and outside a batch until the next microtask. */
+    #queued = [];
+    /** Whether a microtask is queued to apply `#queued` in a batch of its own. */
+    #scheduled = false;
+    /**
+     * The runtime's end, still to reach the watches: `queued` after the queued calls' batch, `frame` after the current
+     * batch's frame (a retirement and an end in one batch: the retirement first).
+     */
+    #ending = "none";
+    /** The ops of the current batch's frame (kept only while watched), and whether a retirement came in it. */
+    #ops = [];
+    #retired = false;
+    #listed = false;
+    constructor(attach, owner, batch) {
+        super(batch);
+        this.#attach = attach;
+        this.#owner = owner;
+    }
+    get value() {
+        if (this.#value === undefined) {
+            throw new ChordError({
+                code: "not_ready",
+                message: `${this.#owner.label}: a followed source read before it attached`,
+            });
+        }
+        return this.#value;
+    }
+    /**
+     * Attaches (activation, after the natives opened): the calls that came meanwhile apply on the attachment's value,
+     * and an end that came meanwhile takes effect then (the value stays). A rejected attachment, or `undefined` (an
+     * absent address), throws; an attachment arriving after its attempt detached the source is detached at once.
+     */
+    async attach(context) {
+        const observer = {
+            advance: (call) => this.#advance(call),
+            end: (end) => this.#end(end),
+        };
+        const attached = await this.#attach(observer, context);
+        if (attached === undefined) {
+            throw new ChordError({ code: "unavailable", message: `${this.#owner.label}: the followed address is absent` });
+        }
+        const state = this.#state;
+        const detach = () => attached.detach();
+        if (state.kind !== "attaching") {
+            detach();
+            return;
+        }
+        this.#value = attached.value;
+        // Nothing watches it yet (members are checked after this): the queued calls only move the value on.
+        for (const call of this.#queued)
+            if (call.kind === "value")
+                this.#value = call.value;
+        this.#queued = [];
+        this.#state = state.end?.kind === "ended" ? { kind: "ended", detach } : { kind: "attached", detach };
+    }
+    /** Its attempt ended: the observer is detached (also after the runtime ended it) and its watches end `ended`. */
+    detach() {
+        const state = this.#state;
+        this.#state = { kind: "detached" };
+        this.#queued = [];
+        if (state.kind === "attached" || state.kind === "ended")
+            state.detach();
+        this.endWatches();
+    }
+    /** A watch of an ended source opens at its value and ends `ended` at once. */
+    openWatch(context) {
+        const watch = super.openWatch(context);
+        if (this.#over)
+            watch.end(ENDED);
+        return watch;
+    }
+    /** A subscriber of an ended source (a reference's watch through its member) ends `ended` at once. */
+    subscribe(subscriber) {
+        if (this.#over)
+            subscriber.end(ENDED);
+        else
+            super.subscribe(subscriber);
+    }
+    deliver(context) {
+        const ops = this.#ops;
+        const retired = this.#retired;
+        this.#ops = [];
+        this.#retired = false;
+        this.#listed = false;
+        this.publish(this.#value, ops.length === 0 ? NO_OPS : ops, retired, context);
+        if (this.#ending === "frame") {
+            this.#ending = "none";
+            this.endWatchesAfterDelivery();
+        }
+    }
+    /** Whether nothing reaches its watches any more: ended by the runtime (what it gave delivered) or detached. */
+    get #over() {
+        const { kind } = this.#state;
+        return (kind === "ended" && this.#ending === "none") || kind === "detached";
+    }
+    /**
+     * A call of the runtime: before the attachment, queued; inside a running batch, applied there (after what was
+     * queued); outside one, queued for one batch on the next microtask.
+     */
+    #advance(call) {
+        const { kind } = this.#state;
+        if (kind === "ended" || kind === "detached")
+            return;
+        if (kind === "attaching" || !this.batch.running) {
+            this.#queued.push(call);
+            if (kind === "attached")
+                this.#schedule();
+            return;
+        }
+        this.#applyQueued();
+        this.#apply(call);
+    }
+    /**
+     * The runtime ended its observer (R4); its attempt is told. `ended` is final: what came before reaches the watches
+     * first (the queued calls in their batch, a call of the running batch in its frame), then they end, the value
+     * staying. A `failed` attempt detaches the source.
+     */
+    #end(end) {
+        const state = this.#state;
+        if (state.kind === "ended" || state.kind === "detached")
+            return;
+        if (state.kind === "attaching") {
+            if (state.end === undefined)
+                this.#state = { kind: "attaching", end };
+            this.#owner.ended(end);
+            return;
+        }
+        if (end.kind === "ended") {
+            this.#state = { kind: "ended", detach: state.detach };
+            if (this.#queued.length > 0 && !this.batch.running)
+                this.#ending = "queued";
+            else {
+                // Inside a running batch the queued calls join it (none is queued outside one: they wait for their batch).
+                this.#applyQueued();
+                this.#endAfterFrame();
+            }
+        }
+        this.#owner.ended(end);
+    }
+    /** The watches end once this batch's frame reached them, at once when the source is in none. */
+    #endAfterFrame() {
+        // No frame to wait for (nothing watches it): the end is over now, and a later watch ends at once.
+        this.#ending = this.#listed ? "frame" : "none";
+        if (!this.#listed)
+            this.endWatchesAfterDelivery();
+    }
+    #schedule() {
+        if (this.#scheduled)
+            return;
+        this.#scheduled = true;
+        this.batch.soon(() => {
+            this.#scheduled = false;
+            const { kind } = this.#state;
+            if (kind === "attached" || kind === "ended")
+                this.#applyQueued();
+            if (this.#ending === "queued")
+                this.#endAfterFrame();
+        }, this.#owner.context);
+    }
+    #applyQueued() {
+        const queued = this.#queued;
+        if (queued.length === 0)
+            return;
+        this.#queued = [];
+        for (const call of queued)
+            this.#apply(call);
+    }
+    /** Applies one value call inside the running batch: the new value, its ops for the frame, the source marked once. */
+    #apply(call) {
+        // The runtime's failures are final: it ends its observer instead of sending one.
+        if (call.kind !== "value")
+            return;
+        this.#value = call.value;
+        if (call.retired)
+            this.#retired = true;
+        if (!this.watched) {
+            this.changed();
+            if (call.retired)
+                this.retiredInBatch();
+            return;
+        }
+        for (const op of call.ops)
+            this.#ops.push(op);
+        if (!this.#listed) {
+            this.#listed = true;
+            this.changed();
+        }
+        if (call.retired)
+            this.retiredInBatch();
+    }
+}
+//# sourceMappingURL=follow.js.map

package/dist/next/host/follow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.js","sourceRoot":"","sources":["../../../src/next/host/follow.ts"],"names":[],"mappings":"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","sourcesContent":["// Followed sources (slice 6b D9, R4, §3): `self.follow(attach)`, a Chord source over a synchronous observer of another\n// runtime (Durable's `observeConversation`, `observeTaskGraph`, `observeDoc`). Attached during its attempt's\n// activation, detached at the attempt's end. Calls inside a running batch (Durable adopting in the store's commit step)\n// are marked in that batch, calls outside one are grouped into one batch on the next microtask, so a derive over two\n// views of one commit computes once with both changes.\n\nimport type { Context } from \"../../context/index.ts\";\nimport type { Op } from \"../../delta/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\nimport type { Watch, WatchCall, WatchEnd } from \"../../watch.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { type Batch, Source, type Subscriber } from \"../state/internal.ts\";\n\n/** The observer a followed runtime is given: Chord's watch shapes (Durable's `Observer`). */\nexport type FollowObserver<T> = {\n\t/** One change, synchronously and quickly: Chord only records it. */\n\tadvance(call: WatchCall<T>, context: Context): void;\n\t/** The followed source ended: `failed` (its runtime failed), or `ended` for good. */\n\tend(end: WatchEnd): void;\n};\n\n/** What attaching gives: the value every later call starts from, and how to detach (Durable's `Observation`). */\nexport type FollowAttachment<T> = { readonly value: T; detach(): void };\n\n/**\n * What `self.follow` takes: attaches `observer`, resolving with the attachment, `undefined` for an absent address.\n * The observer takes calls of any value (it only records them), so `T` is inferred from the attachment alone.\n */\nexport type FollowAttach<T> = (\n\tobserver: FollowObserver<unknown>,\n\tcontext: Context,\n) => Promise<FollowAttachment<T> | undefined>;\n\n/** Who a followed source belongs to: its attempt (R4) and its context. */\nexport type FollowOwner = {\n\treadonly label: string;\n\treadonly context: Context;\n\t/**\n\t * The followed runtime ended its observer: `failed` fails the attempt `transient` (live or activating, its retry\n\t * attaches again); `ended` while the attempt activates fails it `transient` too (it would go live on a source that\n\t * ended); `ended` while live is final for the source only.\n\t */\n\tended(end: WatchEnd): void;\n};\n\n/**\n * Where a followed source stands: waiting for its attachment (with the runtime's end when it came first), attached,\n * ended by the runtime (its value stays; detached at its attempt's end), or detached by its attempt.\n */\ntype FollowState =\n\t| { readonly kind: \"attaching\"; readonly end: WatchEnd | undefined }\n\t| { readonly kind: \"attached\"; readonly detach: () => void }\n\t| { readonly kind: \"ended\"; readonly detach: () => void }\n\t| { readonly kind: \"detached\" };\n\nconst NO_OPS: readonly Op[] = [];\n\nconst ENDED: WatchEnd = { kind: \"ended\" };\n\n/** A followed source: the runtime's value, its calls applied in order, its frames delivered in the host's batch. */\nexport class FollowSource extends Source {\n\treadonly #attach: FollowAttach<JsonValue>;\n\treadonly #owner: FollowOwner;\n\t#state: FollowState = { kind: \"attaching\", end: undefined };\n\t#value: JsonValue | undefined;\n\t/** Calls not applied yet: before the attachment resolved, and outside a batch until the next microtask. */\n\t#queued: WatchCall<JsonValue>[] = [];\n\t/** Whether a microtask is queued to apply `#queued` in a batch of its own. */\n\t#scheduled = false;\n\t/**\n\t * The runtime's end, still to reach the watches: `queued` after the queued calls' batch, `frame` after the current\n\t * batch's frame (a retirement and an end in one batch: the retirement first).\n\t */\n\t#ending: \"none\" | \"queued\" | \"frame\" = \"none\";\n\t/** The ops of the current batch's frame (kept only while watched), and whether a retirement came in it. */\n\t#ops: Op[] = [];\n\t#retired = false;\n\t#listed = false;\n\n\tconstructor(attach: FollowAttach<JsonValue>, owner: FollowOwner, batch: Batch) {\n\t\tsuper(batch);\n\t\tthis.#attach = attach;\n\t\tthis.#owner = owner;\n\t}\n\n\tget value(): JsonValue {\n\t\tif (this.#value === undefined) {\n\t\t\tthrow new ChordError({\n\t\t\t\tcode: \"not_ready\",\n\t\t\t\tmessage: `${this.#owner.label}: a followed source read before it attached`,\n\t\t\t});\n\t\t}\n\t\treturn this.#value;\n\t}\n\n\t/**\n\t * Attaches (activation, after the natives opened): the calls that came meanwhile apply on the attachment's value,\n\t * and an end that came meanwhile takes effect then (the value stays). A rejected attachment, or `undefined` (an\n\t * absent address), throws; an attachment arriving after its attempt detached the source is detached at once.\n\t */\n\tasync attach(context: Context): Promise<void> {\n\t\tconst observer: FollowObserver<JsonValue> = {\n\t\t\tadvance: (call) => this.#advance(call),\n\t\t\tend: (end) => this.#end(end),\n\t\t};\n\t\tconst attached = await this.#attach(observer, context);\n\t\tif (attached === undefined) {\n\t\t\tthrow new ChordError({ code: \"unavailable\", message: `${this.#owner.label}: the followed address is absent` });\n\t\t}\n\t\tconst state = this.#state;\n\t\tconst detach = () => attached.detach();\n\t\tif (state.kind !== \"attaching\") {\n\t\t\tdetach();\n\t\t\treturn;\n\t\t}\n\t\tthis.#value = attached.value;\n\t\t// Nothing watches it yet (members are checked after this): the queued calls only move the value on.\n\t\tfor (const call of this.#queued) if (call.kind === \"value\") this.#value = call.value;\n\t\tthis.#queued = [];\n\t\tthis.#state = state.end?.kind === \"ended\" ? { kind: \"ended\", detach } : { kind: \"attached\", detach };\n\t}\n\n\t/** Its attempt ended: the observer is detached (also after the runtime ended it) and its watches end `ended`. */\n\tdetach(): void {\n\t\tconst state = this.#state;\n\t\tthis.#state = { kind: \"detached\" };\n\t\tthis.#queued = [];\n\t\tif (state.kind === \"attached\" || state.kind === \"ended\") state.detach();\n\t\tthis.endWatches();\n\t}\n\n\t/** A watch of an ended source opens at its value and ends `ended` at once. */\n\toverride openWatch(context: Context): Watch<JsonValue> {\n\t\tconst watch = super.openWatch(context);\n\t\tif (this.#over) watch.end(ENDED);\n\t\treturn watch;\n\t}\n\n\t/** A subscriber of an ended source (a reference's watch through its member) ends `ended` at once. */\n\toverride subscribe(subscriber: Subscriber): void {\n\t\tif (this.#over) subscriber.end(ENDED);\n\t\telse super.subscribe(subscriber);\n\t}\n\n\tdeliver(context: Context): void {\n\t\tconst ops = this.#ops;\n\t\tconst retired = this.#retired;\n\t\tthis.#ops = [];\n\t\tthis.#retired = false;\n\t\tthis.#listed = false;\n\t\tthis.publish(this.#value!, ops.length === 0 ? NO_OPS : ops, retired, context);\n\t\tif (this.#ending === \"frame\") {\n\t\t\tthis.#ending = \"none\";\n\t\t\tthis.endWatchesAfterDelivery();\n\t\t}\n\t}\n\n\t/** Whether nothing reaches its watches any more: ended by the runtime (what it gave delivered) or detached. */\n\tget #over(): boolean {\n\t\tconst { kind } = this.#state;\n\t\treturn (kind === \"ended\" && this.#ending === \"none\") || kind === \"detached\";\n\t}\n\n\t/**\n\t * A call of the runtime: before the attachment, queued; inside a running batch, applied there (after what was\n\t * queued); outside one, queued for one batch on the next microtask.\n\t */\n\t#advance(call: WatchCall<JsonValue>): void {\n\t\tconst { kind } = this.#state;\n\t\tif (kind === \"ended\" || kind === \"detached\") return;\n\t\tif (kind === \"attaching\" || !this.batch.running) {\n\t\t\tthis.#queued.push(call);\n\t\t\tif (kind === \"attached\") this.#schedule();\n\t\t\treturn;\n\t\t}\n\t\tthis.#applyQueued();\n\t\tthis.#apply(call);\n\t}\n\n\t/**\n\t * The runtime ended its observer (R4); its attempt is told. `ended` is final: what came before reaches the watches\n\t * first (the queued calls in their batch, a call of the running batch in its frame), then they end, the value\n\t * staying. A `failed` attempt detaches the source.\n\t */\n\t#end(end: WatchEnd): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"ended\" || state.kind === \"detached\") return;\n\t\tif (state.kind === \"attaching\") {\n\t\t\tif (state.end === undefined) this.#state = { kind: \"attaching\", end };\n\t\t\tthis.#owner.ended(end);\n\t\t\treturn;\n\t\t}\n\t\tif (end.kind === \"ended\") {\n\t\t\tthis.#state = { kind: \"ended\", detach: state.detach };\n\t\t\tif (this.#queued.length > 0 && !this.batch.running) this.#ending = \"queued\";\n\t\t\telse {\n\t\t\t\t// Inside a running batch the queued calls join it (none is queued outside one: they wait for their batch).\n\t\t\t\tthis.#applyQueued();\n\t\t\t\tthis.#endAfterFrame();\n\t\t\t}\n\t\t}\n\t\tthis.#owner.ended(end);\n\t}\n\n\t/** The watches end once this batch's frame reached them, at once when the source is in none. */\n\t#endAfterFrame(): void {\n\t\t// No frame to wait for (nothing watches it): the end is over now, and a later watch ends at once.\n\t\tthis.#ending = this.#listed ? \"frame\" : \"none\";\n\t\tif (!this.#listed) this.endWatchesAfterDelivery();\n\t}\n\n\t#schedule(): void {\n\t\tif (this.#scheduled) return;\n\t\tthis.#scheduled = true;\n\t\tthis.batch.soon(() => {\n\t\t\tthis.#scheduled = false;\n\t\t\tconst { kind } = this.#state;\n\t\t\tif (kind === \"attached\" || kind === \"ended\") this.#applyQueued();\n\t\t\tif (this.#ending === \"queued\") this.#endAfterFrame();\n\t\t}, this.#owner.context);\n\t}\n\n\t#applyQueued(): void {\n\t\tconst queued = this.#queued;\n\t\tif (queued.length === 0) return;\n\t\tthis.#queued = [];\n\t\tfor (const call of queued) this.#apply(call);\n\t}\n\n\t/** Applies one value call inside the running batch: the new value, its ops for the frame, the source marked once. */\n\t#apply(call: WatchCall<JsonValue>): void {\n\t\t// The runtime's failures are final: it ends its observer instead of sending one.\n\t\tif (call.kind !== \"value\") return;\n\t\tthis.#value = call.value;\n\t\tif (call.retired) this.#retired = true;\n\t\tif (!this.watched) {\n\t\t\tthis.changed();\n\t\t\tif (call.retired) this.retiredInBatch();\n\t\t\treturn;\n\t\t}\n\t\tfor (const op of call.ops) this.#ops.push(op);\n\t\tif (!this.#listed) {\n\t\t\tthis.#listed = true;\n\t\t\tthis.changed();\n\t\t}\n\t\tif (call.retired) this.retiredInBatch();\n\t}\n}\n"]}