@synapse-sdk/client 0.3.3 → 0.3.4

package/dist/synapse.js

@@ -2,17 +2,17 @@
 // loop (`node.ts`) drives sessions; publishers, registrations, subscriptions and namespaces are their
 // own tasks, told about sessions by the loop; every fact about the world is read from the current
 // `Session` (the runtime's statement) at the moment it is asked for, never copied here.
-import { ClockSync, SynapseError, ageOf, defaultDomId, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, toLocalUs, } from "@synapse-sdk/core";
-import { callStream, startOn } from "./calls.js";
-import { Node, resolveTarget, startNode } from "./node.js";
+import { SynapseError, ageOf, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, } from "@synapse-sdk/core";
+import { callStream, failedRun, startOn } from "./calls.js";
+import { Node, createNode, endpointDial, resolveTarget } from "./node.js";
 import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
 import { Namespace, StoreHandleImpl, attachStore, openStore } from "./store.js";
 import { TasksFacet } from "./tasks.js";
 import { PublisherHandle, TopicPublisher, TopicSubscription, wasmFor } from "./topics.js";
 import { TopicView } from "./view.js";
-/** How long the first `connect()` keeps trying a retryable failure before `failed` (SDK §2: the first connect is bounded). */
-export const FIRST_CONNECT_GIVE_UP_MS = 30_000;
+import { watchState } from "./util.js";
+export { FIRST_CONNECT_GIVE_UP_MS } from "./node.js";
 /** The descriptor a publisher of `contract` on node `n` declares (as `TopicPublisher` builds it: a `fec` symbol size of 0 is the node's). */
 function wantedDesc(contract, n) {
     const d = contract.desc(n.dom);
@@ -24,73 +24,140 @@ function wantedDesc(contract, n) {
 function descKey(d) {
     return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null });
 }
+/**
+ * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`): `read` is the fact now, the same
+ * object while it is unchanged. It changes with the node's link and, while connected, with the current session's values
+ * that `watched` names; a callback is rebound to the new session's values on every link change.
+ */
+class NodeCell {
+    node;
+    read;
+    watched;
+    constructor(node, read, watched) {
+        this.node = node;
+        this.read = read;
+        this.watched = watched;
+    }
+    get() { return this.read(); }
+    /** `cb` with the value on each change of what it is read from; returns the remover. */
+    onChange(cb) {
+        const listener = () => cb(this.read());
+        let un = [];
+        const bind = () => {
+            for (const u of un)
+                u();
+            const s = this.node.currentSession();
+            un = s ? this.watched(s).map(c => c.subscribe(listener)) : [];
+        };
+        bind();
+        const unLink = this.node.link.subscribe(() => { bind(); listener(); });
+        return () => { unLink(); for (const u of un)
+            u(); };
+    }
+    /** The value after its next change; once the node ends, the value then, whether or not it changed (nothing will change any more). */
+    changed() {
+        const from = this.read();
+        if (this.node.isEnded)
+            return Promise.resolve(from);
+        return new Promise(resolve => {
+            let done = false;
+            const finish = (v) => { if (done)
+                return; done = true; un(); resolve(v); };
+            const un = this.onChange(v => { if (v !== from)
+                finish(v); });
+            void this.node.ended.promise.then(() => finish(this.read()));
+        });
+    }
+    /** The value after each change; ends when the node ends. */
+    watch() { return watchState(cb => this.onChange(cb), this.read, () => this.node.isEnded); }
+}
+const NO_TOPICS = Object.freeze({});
+const NO_SERVICES = Object.freeze({});
 export class Synapse {
     #node;
-    #connecting;
-    #starting;
     #publishers = new Map();
     #stores = new Map();
     warn;
-    // Private: the options hold the token and the credential, which nothing prints.
-    #opts;
+    /**
+     * The node, usable at once and `idle` (no target) until `connect()`: constructing opens no connection. Where to connect
+     * (the url, its token, the certificate pin) is the target's, given to `connect()`. Throws `invalid_input` for options
+     * that can never work (a bad `name`).
+     */
     constructor(opts) {
-        this.#opts = opts;
         this.warn = msg => console.warn(`[synapse] ${msg}`);
+        const n = this.#node = createNode(opts);
+        let lastLink = n.link.get(), lastState = n.state();
+        this.status = new NodeCell(n, () => {
+            const l = n.link.get();
+            if (l !== lastLink) {
+                lastLink = l;
+                lastState = n.state();
+            }
+            return lastState;
+        }, () => []);
+        let lastCatalog;
+        this.catalog = new NodeCell(n, () => {
+            const s = n.currentSession();
+            const topics = s?.topics.get().topics ?? NO_TOPICS, services = s?.services.get().services ?? NO_SERVICES;
+            if (lastCatalog?.topics !== topics || lastCatalog.services !== services)
+                lastCatalog = { topics, services, describe: name => services[name]?.card };
+            return lastCatalog;
+        }, s => [s.topics, s.services]);
+        this.project = new NodeCell(n, () => n.currentSession()?.project.get(), s => [s.project]);
     }
-    /** `await Synapse.connect(opts)`: a node with a session, or the reason there is none. */
-    static connect(opts) { return new Synapse(opts).connect(); }
-    /** Connects (once; later calls return the same promise). Resolves once a session is established. */
-    connect() {
-        this.#connecting ??= (async () => {
-            const started = startNode(this.#opts, FIRST_CONNECT_GIVE_UP_MS);
-            // The node as soon as its loop runs (or none: the options were refused), for a `close()` during the first dial.
-            this.#starting = started.then(s => s.node, () => undefined);
-            const { node, connected } = await started;
-            await connected;
-            this.#node = node;
-            return this;
-        })();
-        return this.#connecting;
-    }
-    get node() {
-        if (!this.#node)
-            throw new SynapseError("not_connected", "connect() has not completed");
-        return this.#node;
-    }
-    #session() { return this.node.currentSession(); }
-    // ------------------------------------------------------------------------------ lifecycle
-    get status() { return this.#node?.state() ?? { status: "connecting", attempt: 1 }; }
-    get connected() { return this.#node?.isConnected ?? false; }
-    /** Called on every change of the connection state; returns the unsubscribe. */
-    watchStatus(cb) { return this.node.link.subscribe(() => cb(this.node.state())); }
-    /** Resolves on the next connected session (at once if connected); rejects once the node ended. */
-    whenConnected() {
-        const n = this.node;
-        if (n.isConnected)
-            return Promise.resolve();
+    /**
+     * Connects the node to `target` (a string is the url), the one connect verb: the first connect, and how an HMI moves
+     * from one robot's runtime to another. The current session, if any, is torn down before `target` is dialed; every
+     * handle re-binds to the new session as across a reconnect. Identity fields `target` leaves out keep the node's.
+     *
+     * Operator intent is never lost under quick clicking: the newest call wins. The node works toward its latest target; a
+     * call superseded by a newer `connect()` or `disconnect()` resolves quietly. The target already declared declares
+     * nothing and settles with it, except from its own `failed`, where it is dialed again.
+     *
+     * Bounded (SDK §2): a retryable failure is tried again, paced by the reconnect policy, until `FIRST_CONNECT_GIVE_UP_MS`
+     * after the first attempt, a hard bound (an attempt still outstanding then is cut); `unauthorized` gives up at once.
+     * Resolves once a session to *this* target is connected (or a newer call superseded it). Rejects with this target's
+     * error when the node rests `failed` (still usable: `connect()` dials again), `invalid_input` at once for a malformed
+     * target, `not_connected` once the node has ended (`close()`).
+     *
+     * With no target: the declared target, if there is one (settles with it, as above), else `SYNAPSE_ENDPOINT` (Bun/Node;
+     * the runtime sets it for every task it starts); neither (or a browser) is `invalid_input` and the node stays `idle`.
+     *
+     * The outcome is handled: `node.connect(url);` without a handler is safe (`useConnection()` shows `failed`); `await` still rejects.
+     */
+    connect(target) {
+        const n = this.#node;
+        let p;
         if (n.isEnded)
-            return Promise.reject(new SynapseError("not_connected", "node closed"));
-        return new Promise((resolve, reject) => {
-            const un = n.link.subscribe(l => { if (l.status === "connected") {
-                un();
-                resolve();
-            } });
-            // The node's end settles it (a resolved promise ignores the later reject).
-            void n.ended.promise.then(() => { un(); reject(new SynapseError("not_connected", "node closed")); });
-        });
-    }
-    /** Declares a new target (broker, identity); resolves once connected to it (or rejects with why not). `null` disconnects for good. */
-    setTarget(target) { return this.node.setTarget(target ? resolveTarget(this.node, target) : undefined); }
-    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended. */
-    /** During the first `connect()` it ends that attempt: the node ends `closed` and `connect()` rejects `not_connected`. */
-    async close() {
-        const n = this.#node ?? (await this.#starting);
-        if (n)
-            await n.close();
+            p = Promise.reject(new SynapseError("not_connected", "node closed"));
+        else {
+            let dial;
+            try {
+                dial = target === undefined ? (n.target.get().dial ?? endpointDial(n)) : resolveTarget(n, typeof target === "string" ? { url: target } : target);
+            }
+            catch (e) {
+                return Promise.reject(e);
+            }
+            p = n.declare(dial).then(() => this);
+        }
+        p.catch(() => { });
+        return p;
     }
+    /**
+     * Disconnects: the session, if any, is torn down and the node rests `idle` (no target), not ended. Every handle is kept,
+     * exactly as between two sessions, and a later `connect()` dials again. A `connect()` still pursuing is superseded (it
+     * resolves quietly). Resolves once the session is gone; already `idle`: at once. `not_connected` once the node has ended.
+     */
+    disconnect() { return this.#node.declare(undefined); }
+    /** The node's engine (the SDK's own modules and tests use it). */
+    get node() { return this.#node; }
+    #session() { return this.#node.currentSession(); }
+    // ------------------------------------------------------------------------------ lifecycle
+    /** Where the node stands (`ConnectionState`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */
+    status;
+    /** Tells the runtime we are leaving, ends every handle, and resolves once the node has ended (`closed`, for good). A `connect()` in flight rejects `not_connected`. */
+    async close() { await this.#node.close(); }
     async [Symbol.asyncDispose]() { await this.close(); }
-    /** Resolves once the node has ended (closed, failed, or the policy gave up). */
-    get ended() { return this.node.ended.promise; }
     info() {
         const n = this.node;
         const id = n.target.get().identity;
@@ -98,21 +165,17 @@ export class Synapse {
         return { name: id.name ?? "", type: id.type, userId: id.user_id, prefix: s?.prefix ?? "", role: s?.role ?? "observer", dom: n.dom, brokerDom: s?.hello.dom ?? "", brokerVersion: s?.hello.broker_version ?? "", robot: s?.hello.robot ?? "", runtimeName: s?.hello.runtime_name ?? "", runtimeId: s?.hello.runtime_id ?? "", url: n.target.get().dial?.url ?? "" };
     }
     metrics() { const n = this.node; return { sessions: n.epochs, reconnects: n.reconnects, callsSent: n.callsSent, callsAnswered: n.callsAnswered }; }
-    /** Broker notices addressed to this node (an error body on `res` without a call). */
-    onNotice(cb) { this.node.notices.add(cb); return () => { this.node.notices.delete(cb); }; }
-    /** `promoted`/`demoted` notices (WP §3.5). */
-    onProjectNotice(cb) { this.node.projectNotices.add(cb); return () => { this.node.projectNotices.delete(cb); }; }
+    /** Notices addressed to this node: `cb` per notice (an error body on `res` without a call, and a refused live override claim of this node's scene); returns the unsubscribe. */
+    notices(cb) { this.node.notices.add(cb); return () => { this.node.notices.delete(cb); }; }
     // ---------------------------------------------------------------------------------- clock
     nowUs() { return nowUs(); }
-    clock() { const s = this.#session(); return s ? s.clock.get() : new ClockSync(this.node.dom.id, "", 0).info(); }
-    timeOffsets() { return this.#session()?.timeOffsets.get() ?? {}; }
-    /** A publisher stamp in our clock (WP §7.4), when the offsets allow it. */
-    toLocalUs(tUs, dom) { const s = this.#session(); return s ? toLocalUs(s.clock.get(), s.timeOffsets.get(), tUs, dom) : undefined; }
     /** How old a message is now, in our clock. */
     ageUs(env) { const s = this.#session(); return s ? ageOf(s.clock.get(), s.timeOffsets.get(), env.tUs, env.dom, nowUs()) : undefined; }
     async publisher(topic) {
         const contract = resolveTopic(topic);
         const n = this.node;
+        // Its descriptor names the node's time domain: final before any publisher is made.
+        await n.prepared;
         const name = contract.name;
         let p;
         let held;
@@ -157,9 +220,13 @@ export class Synapse {
         }
         return h;
     }
-    subscribe(topic, opts = {}) {
+    subscribe(topic, cbOrOpts, opts = {}) {
         const contract = resolveTopic(topic);
-        return new TopicSubscription(this.node, contract, opts, this.warn);
+        if (typeof cbOrOpts !== "function")
+            return new TopicSubscription(this.node, contract, cbOrOpts ?? {}, this.warn);
+        const sub = new TopicSubscription(this.node, contract, opts, this.warn);
+        sub.deliverTo(cbOrOpts);
+        return sub;
     }
     view(topic, opts = {}) {
         const contract = resolveTopic(topic);
@@ -169,7 +236,7 @@ export class Synapse {
     call(svc, args = {}, opts = {}) {
         const s = this.#session();
         if (!s)
-            throw new SynapseError("not_connected", "no session: the call was not sent");
+            return failedRun(new SynapseError("not_connected", "no session: the call was not sent"));
         const contract = isServiceContract(svc) ? svc : undefined;
         return startOn(this.node, s, serviceName(svc), args, opts, contract);
     }
@@ -204,57 +271,57 @@ export class Synapse {
     // ---------------------------------------------------------------------------------- store
     /** Opens namespace `name` (SDK §9); resolves once the mirror is in (or the namespace is known absent). */
     store(name, opts = {}) { return openStore(this.node, this.#stores, name, opts, this.warn); }
-    /** The runtime's `config` namespace (operators write it). */
-    config(opts = {}) { return this.store("config", opts); }
     // ---------------------------------------------------------------------------------- scene
     #scenes = { current: undefined };
     /** The active project's scene (PLAN v0.24 §5); resolves attached, or at once `detached` when no project is active. */
     scene() { return openScene(this.node, this.#scenes, this.warn); }
     // -------------------------------------------------------------------------------- catalog
-    /** The runtime's catalogs as the current session last read them; empty between sessions. */
-    get catalog() {
-        const s = this.#session();
-        const topics = s?.topics.get().topics ?? {};
-        const services = s?.services.get().services ?? {};
-        return { topics, services, describe: name => services[name]?.card };
-    }
-    /** Called when either catalog changes on the current session. */
-    watchCatalog(cb) {
-        let un = [];
-        const bind = () => {
-            for (const u of un)
-                u();
-            un = [];
-            const s = this.#session();
-            if (!s)
-                return;
-            un.push(s.topics.subscribe(() => cb(this.catalog)), s.services.subscribe(() => cb(this.catalog)));
-        };
-        bind();
-        const unLink = this.node.link.subscribe(() => { bind(); cb(this.catalog); });
-        return () => { unLink(); for (const u of un)
-            u(); };
-    }
+    /** The runtime's catalogs as the current session last read them (empty between sessions), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */
+    catalog;
     // -------------------------------------------------------------------------------- project
-    /** The project state the current session last read (WP §3.5); `undefined` between sessions or before the first snapshot. */
-    project() { return this.#session()?.project.get(); }
-    watchProject(cb) {
-        let un;
-        const bind = () => { un?.(); un = this.#session()?.project.subscribe(p => cb(p)); };
-        bind();
-        const unLink = this.node.link.subscribe(() => { bind(); cb(this.project()); });
-        return () => { unLink(); un?.(); };
+    /** The project state the current session last read (WP §3.5), a state value; `get()` is `undefined` between sessions or before the first snapshot. */
+    project;
+    /**
+     * A project call on the current session. The runtime tells a web session whose role it changed before it answers on
+     * it (the notice, then the answer, on the same `res` track, read in order) and closes it `role_changed` after: a role
+     * that differs from the session's hello grant means the switch is coming, and the call resolves once a session other
+     * than the one it went out on is connected (`not_connected` if the node ends or is disconnected meanwhile, the error
+     * if it rests `failed`). An hmi's role is `hmi` from admission and never changes, so its calls resolve on the answer.
+     */
+    async #projectCall(op, args) {
+        const n = this.node;
+        const asked = n.currentSession();
+        if (!asked)
+            throw new SynapseError("not_connected", "no session: the call was not sent");
+        const snapshot = await startOn(n, asked, `synapse/project/${op}`, args, {}).result;
+        if (asked.role !== asked.hello.role) {
+            // The runtime replaces this session (the role changed): its close is expected, as one we make ourselves, so
+            // @moq/net's track and discovery lines about it are routine (moq_log.ts).
+            asked.log?.closing();
+            await n.switchedFrom(asked);
+        }
+        return snapshot;
     }
-    #projectCall(op, args) { return this.call(`synapse/project/${op}`, args).result; }
-    /** `synapse/project/activate {id}`: activates `id` (or joins it when active); promoted to operator. */
+    /**
+     * `synapse/project/activate {id}`: activates `id` when no project is active, or joins it when it is the active one;
+     * `project_busy` while another project is active (no takeover: deactivate it first). A web node is promoted to
+     * operator and resolves once the session with the new role is connected; an hmi stays `hmi` and resolves on the answer.
+     */
     activateProject(id) { return this.#projectCall("activate", { id }); }
-    /** `synapse/project/deactivate {}`: every operator is demoted. */
+    /**
+     * `synapse/project/deactivate {}`: any operator or hmi may deactivate, except a project an hmi activated
+     * (`active.activated_by_hmi`), which only an hmi may (`not_operator`). Every web operator is demoted; when that
+     * demotes this node, resolves once the demoted session is connected. An hmi is never demoted.
+     */
     deactivateProject() { return this.#projectCall("deactivate", {}); }
-    /** `synapse/project/join {as: "operator"}`: promoted on the active project, or `project_inactive`. */
+    /** `synapse/project/join {as: "operator"}`: an operator of the active project, or `project_inactive`. A web node resolves once the promoted session is connected; an hmi on the answer. */
     joinProject(as = "operator") { return this.#projectCall("join", { as }); }
-    /** `synapse/project/leave {}`: drops our standing (every session of our `user_id`). */
+    /**
+     * `synapse/project/leave {}`: drops our standing. For an hmi membership is per session: this session only (it stays
+     * `hmi`, never closed). For a web node it removes our `user_id`'s web sessions only; when that demotes this node,
+     * resolves once the demoted session is connected.
+     */
     leaveProject() { return this.#projectCall("leave", {}); }
-    getProject() { return this.#projectCall("get", {}); }
     // -------------------------------------------------------------------------------- tasks
     #tasks;
     /**

package/dist/tasks.d.ts

@@ -8,7 +8,7 @@ export declare const TASKS_NAMESPACES: {
     readonly status: "task_status";
     readonly catalog: "task_catalog";
 };
-/** What `status.value` is before the runtime said anything: neither scope's state known, no tasks. */
+/** What `status.get()` is before the runtime said anything: neither scope's state known, no tasks. */
 export declare const EMPTY_TASKS_STATUS: TasksStatus;
 /**
  * `task_status`'s rows as a `TasksStatus`. A run row is the one keyed `robot` or `project`; an instance

package/dist/tasks.js

@@ -7,9 +7,10 @@
 // unchanged part keeps its object.
 import { SynapseError } from "@synapse-sdk/core";
 import { replaceEqualDeep } from "./util.js";
+import { ulid } from "./scene.js";
 /** The namespaces the facet reads and writes (the runtime's names). */
 export const TASKS_NAMESPACES = { declarations: "tasks", status: "task_status", catalog: "task_catalog" };
-/** What `status.value` is before the runtime said anything: neither scope's state known, no tasks. */
+/** What `status.get()` is before the runtime said anything: neither scope's state known, no tasks. */
 export const EMPTY_TASKS_STATUS = { robot: { state: undefined, tasks: {} }, project: { state: undefined, tasks: {} } };
 const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** A run row (`robot` / `project`: `{state, since, reason?}`) as the scope's run fields. */
@@ -49,7 +50,7 @@ export function tasksStatusOf(rows, unplaced = () => { }) {
     return { robot: { ...runOf(rows.robot), tasks: robot }, project: { ...runOf(rows.project), tasks: project } };
 }
 /**
- * A read-only handle over one namespace of the node: `value` is `derive` of the mirror, recomputed only
+ * A read-only handle over one namespace of the node: `get()` is `derive` of the mirror, recomputed only
  * when the mirror changed and shared structurally with the previous value. The namespace is opened on
  * the first touch of any member.
  */
@@ -65,8 +66,8 @@ class DerivedHandle {
         this.#value = empty;
     }
     #handle() { return (this.#h ??= this.open()); }
-    get value() {
-        const rows = this.#handle().value;
+    get() {
+        const rows = this.#handle().get();
         if (rows !== this.#from) {
             this.#from = rows;
             this.#value = replaceEqualDeep(this.#value, this.derive(rows));
@@ -77,9 +78,9 @@ class DerivedHandle {
     ready() { return this.#handle().ready(); }
     async *watch() {
         for await (const _ of this.#handle().watch())
-            yield this.value;
+            yield this.get();
     }
-    subscribe(listener) { return this.#handle().subscribe(listener); }
+    onChange(cb) { return this.#handle().onChange(() => cb(this.get())); }
 }
 /** The robot's declarations: the node's handle on `tasks`; every write waits for the value to be current first. */
 class Declarations {
@@ -89,20 +90,33 @@ class Declarations {
         this.open = open;
     }
     #handle() { return (this.#h ??= this.open()); }
-    get value() { return this.#handle().value; }
-    get(instance) { return this.#handle().get(instance); }
+    get(instance) {
+        const h = this.#handle();
+        return (instance === undefined ? h.get() : h.get(instance));
+    }
     get synced() { return this.#handle().synced; }
     get status() { return this.#handle().status; }
+    changed() { return this.#handle().changed(); }
     ready() { return this.#handle().ready(); }
     async set(a, b) {
         const h = this.#handle();
         await h.ready();
-        await (typeof a === "string" ? h.set(a, b) : h.set(a));
+        if (typeof a === "string") {
+            await h.set(a, b);
+            return;
+        }
+        // One object: a declaration (its `ref` is a string) gets a minted instance; else it is a map of declarations.
+        if (typeof a.ref === "string") {
+            const instance = ulid();
+            await h.set(instance, a);
+            return instance;
+        }
+        await h.set(a);
     }
     async delete(instance) { const h = this.#handle(); await h.ready(); await h.delete(instance); }
     async clear() { const h = this.#handle(); await h.ready(); await h.clear(); }
     watch(instance) { return this.#handle().watch(instance); }
-    subscribe(listener) { return this.#handle().subscribe(listener); }
+    onChange(cb) { return this.#handle().onChange(cb); }
 }
 /** `node.tasks`. `attach(name)` hands out the node's handle on a namespace; `call` starts a call on the current session. */
 export class TasksFacet {

package/dist/topics.d.ts

@@ -147,5 +147,7 @@ export declare class TopicSubscription<T> implements Subscription<T> {
     /** Ends the subscription: the follow task stops, every track is closed, a pending `next()` returns `undefined`. */
     unsubscribe(): void;
     [Symbol.asyncDispose](): Promise<void>;
+    /** The callback form's read loop (`node.subscribe(topic, cb)`): `cb` with each batch `next()` returns, until the subscription ends; a throwing `cb` is rethrown later and the loop goes on. */
+    deliverTo(cb: (batch: Envelope<T>[]) => void): void;
 }
 export {};

package/dist/topics.js

@@ -16,7 +16,7 @@ import { FLAGS, MSGPACK, SynapseError, TYPES, auParamSets, auSyncPoints, decode
 import { Handle, start as startHandle } from "./channel.js";
 import { FecReader, FecWriter, ReportWriter, feedbackListener, requireFec } from "./fec.js";
 import { RETAINED_FRAME_MAX_AGE_MS, StreamWriter, latestSubscription, moqTimestamp, streamTopicSubscription, waitActive, writeLatest } from "./session.js";
-import { AsyncQueue, deferred, withTimeout, TIMEOUT } from "./util.js";
+import { AsyncQueue, deferred, rethrowLater, withTimeout, TIMEOUT } from "./util.js";
 /** moq's cap on one `stream` frame (a group's cache). */
 const STREAM_FRAME_MAX = 32 * 1024 * 1024;
 /** The bound on adding one publisher (its broadcast, its `desc`, its `data` subscription). */
@@ -627,6 +627,22 @@ export class TopicSubscription {
         this.#signal();
     }
     async [Symbol.asyncDispose]() { this.unsubscribe(); }
+    /** The callback form's read loop (`node.subscribe(topic, cb)`): `cb` with each batch `next()` returns, until the subscription ends; a throwing `cb` is rethrown later and the loop goes on. */
+    deliverTo(cb) {
+        void (async () => {
+            for (;;) {
+                const b = await this.next();
+                if (!b)
+                    return;
+                try {
+                    cb(b);
+                }
+                catch (e) {
+                    rethrowLater(e);
+                }
+            }
+        })();
+    }
 }
 /** A source is done: its subscription and its request are closed (its pending read settles as the end). */
 function closeSource(src) {