@synapse-sdk/client 0.3.0 → 0.3.4

package/dist/util.d.ts

@@ -5,6 +5,19 @@ export interface Deferred<T> {
     settled: boolean;
 }
 export declare function deferred<T>(): Deferred<T>;
+/**
+ * A state value (`node.status`, `node.catalog`, `node.project`, the `status` of the store, scene and tasks handles):
+ * `get()` the value now (the same object while it is unchanged), `onChange` for each change (the framework bridge;
+ * `cb` gets the value; returns the remover), `changed()` for the value after the next change (at once with the value
+ * now once the node has ended), `watch()` for the value after each change in a loop (ends when the node, or the
+ * handle, ends). Not exported from the package: no user builds one.
+ */
+export interface StateValue<T> {
+    get(): T;
+    onChange(cb: (value: T) => void): () => void;
+    changed(): Promise<T>;
+    watch(): AsyncIterable<T>;
+}
 /** A value plus listeners. `changed()` resolves on the next `set`. */
 export declare class Cell<T> {
     #private;
@@ -16,6 +29,8 @@ export declare class Cell<T> {
     changed(): Promise<T>;
     get listenerCount(): number;
 }
+/** A callback's throw, rethrown on its own microtask: the caller's loop goes on and the error still surfaces. */
+export declare const rethrowLater: (e: unknown) => void;
 export declare const DONE: unique symbol;
 /**
  * Bounded FIFO with one consumer. `push` never blocks: past `capacity` the oldest item is dropped
@@ -65,3 +80,31 @@ export declare class Ring {
     push(v: number): void;
     percentile(p: number): number | undefined;
 }
+/**
+ * The loop form of a state value (`watch()`), built from its `onChange` and `get`: the value after each change, compared
+ * by reference (a state value keeps its object while unchanged), changes in between folded into the latest (state, not
+ * history). It ends when it is told of a change once `ended()` holds; each state value tells its listeners when it ends.
+ * Leaving the loop removes the listener.
+ */
+export declare function watchState<T>(onChange: (cb: () => void) => () => void, get: () => T, ended: () => boolean): AsyncGenerator<T, void, undefined>;
+/**
+ * A handle's own state as a state value (`store.status`, `scene.status`; the `StateValue` shape): `get()` is `read()`
+ * kept the same object while every field is equal (`shallowEqual`), `onChange` calls back only when that object
+ * changes, `changed()` resolves with the next one (at once with the value now once `ended()`), `watch()` is the loop
+ * form. `source` is what tells of a possible change: the handle's own notifications.
+ */
+export declare class StatusCell<T> {
+    #private;
+    private readonly read;
+    private readonly source;
+    private readonly ended;
+    constructor(read: () => T, source: (l: () => void) => () => void, ended: () => boolean);
+    get(): T;
+    /** `cb` with the value on each change; once the handle has ended (or this state value was disposed) nothing will change: a no-op remover. */
+    onChange(cb: (value: T) => void): () => void;
+    /** The handle closed: every upstream registration is removed (after the listeners were told of the close); new subscriptions are refused. */
+    dispose(): void;
+    changed(): Promise<T>;
+    /** The value after each change; ends with the handle. */
+    watch(): AsyncIterable<T>;
+}

package/dist/util.js

@@ -1,4 +1,4 @@
-// Small primitives shared by the client: a value cell with change notification, a bounded async
+// Small primitives shared by the client: a value kept current with change notification, a bounded async
 // queue, deferreds, sleeps that honour AbortSignals, and TanStack-style structural sharing.
 export function deferred() {
     const d = { settled: false };
@@ -34,6 +34,8 @@ export class Cell {
     changed() { this.#waiters ??= deferred(); return this.#waiters.promise; }
     get listenerCount() { return this.#listeners.size; }
 }
+/** A callback's throw, rethrown on its own microtask: the caller's loop goes on and the error still surfaces. */
+export const rethrowLater = (e) => { queueMicrotask(() => { throw e; }); };
 export const DONE = Symbol("done");
 /**
  * Bounded FIFO with one consumer. `push` never blocks: past `capacity` the oldest item is dropped
@@ -225,3 +227,97 @@ export class Ring {
         return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))];
     }
 }
+/**
+ * The loop form of a state value (`watch()`), built from its `onChange` and `get`: the value after each change, compared
+ * by reference (a state value keeps its object while unchanged), changes in between folded into the latest (state, not
+ * history). It ends when it is told of a change once `ended()` holds; each state value tells its listeners when it ends.
+ * Leaving the loop removes the listener.
+ */
+export async function* watchState(onChange, get, ended) {
+    if (ended())
+        return;
+    let changed = false;
+    let wake;
+    const un = onChange(() => { changed = true; wake?.resolve(); });
+    let last = get();
+    try {
+        for (;;) {
+            while (!changed) {
+                wake = deferred();
+                await wake.promise;
+                wake = undefined;
+            }
+            changed = false;
+            if (ended())
+                return;
+            const v = get();
+            if (v === last)
+                continue;
+            last = v;
+            yield v;
+        }
+    }
+    finally {
+        un();
+    }
+}
+/**
+ * A handle's own state as a state value (`store.status`, `scene.status`; the `StateValue` shape): `get()` is `read()`
+ * kept the same object while every field is equal (`shallowEqual`), `onChange` calls back only when that object
+ * changes, `changed()` resolves with the next one (at once with the value now once `ended()`), `watch()` is the loop
+ * form. `source` is what tells of a possible change: the handle's own notifications.
+ */
+export class StatusCell {
+    read;
+    source;
+    ended;
+    #last;
+    /** The upstream registrations of the listeners now subscribed: `dispose()` removes them all. */
+    #subs = new Set();
+    #disposed = false;
+    constructor(read, source, ended) {
+        this.read = read;
+        this.source = source;
+        this.ended = ended;
+    }
+    get() {
+        const v = this.read();
+        if (this.#last === undefined || !shallowEqual(this.#last, v))
+            this.#last = v;
+        return this.#last;
+    }
+    /** `cb` with the value on each change; once the handle has ended (or this state value was disposed) nothing will change: a no-op remover. */
+    onChange(cb) {
+        if (this.#disposed || this.ended())
+            return () => { };
+        let from = this.get();
+        const un = this.source(() => {
+            const v = this.get();
+            if (v === from)
+                return;
+            from = v;
+            cb(v);
+        });
+        this.#subs.add(un);
+        return () => { if (this.#subs.delete(un))
+            un(); };
+    }
+    /** The handle closed: every upstream registration is removed (after the listeners were told of the close); new subscriptions are refused. */
+    dispose() {
+        this.#disposed = true;
+        const subs = [...this.#subs];
+        this.#subs.clear();
+        for (const un of subs)
+            un();
+    }
+    changed() {
+        const from = this.get();
+        if (this.#disposed || this.ended())
+            return Promise.resolve(from);
+        return new Promise(resolve => {
+            const un = this.onChange(v => { un(); resolve(v); });
+        });
+    }
+    /** The value after each change; ends with the handle. */
+    watch() { return watchState(cb => this.onChange(cb), () => this.get(), () => this.#disposed || this.ended()); }
+}

package/dist/view.d.ts

@@ -11,9 +11,11 @@ export declare class TopicView<T, S> implements View<S> {
     ready(): Promise<void>;
     /** Resolves with the state after the next change; a closed view resolves with its final state. */
     changed(): Promise<ViewState<S>>;
-    /** Called on every state change; the returned function removes the listener. */
-    subscribe(listener: () => void): () => void;
-    /** Ends the view for good: the subscription is closed, listeners are dropped, waiters settle, the registry entry is released. */
+    /** `cb` with the state on every change; the returned function removes it. Told once more when the view closes. */
+    onChange(cb: (state: ViewState<S>) => void): () => void;
+    /** The state after each change; ends when the view is closed or the node ends. */
+    watch(): AsyncIterable<ViewState<S>>;
+    /** Ends the view for good: the subscription is closed, listeners are told once and dropped, waiters settle, the registry entry is released. */
     close(): void;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/view.js

@@ -1,10 +1,10 @@
-// A view (SDK §4.3): a topic's value now, as a cell for frameworks — `get()` any time, `subscribe`
-// for changes, `changed()` for the next one, `ready()` for the first. State, not history: of every
+// A view (SDK §4.3): a topic's value now, as a state value — `get()` any time, `onChange` for
+// changes, `changed()` for the next one, `watch()` for each one in a loop, `ready()` for the first. State, not history: of every
 // batch the subscription returns the view keeps the newest envelope (by its publisher's stamp),
 // compared with structural sharing so `get()` is reference-stable while the selected value is
 // deep-equal. The view is subscribed from its creation until `close()`, like the Rust `View`.
 import { SynapseError } from "@synapse-sdk/core";
-import { deferred, replaceEqualDeep } from "./util.js";
+import { deferred, replaceEqualDeep, watchState } from "./util.js";
 export class TopicView {
     node;
     opts;
@@ -43,7 +43,7 @@ export class TopicView {
         const s = this.#state;
         if (s.status === "live" || s.status === "stale")
             d.resolve();
-        else if (s.connection === "closed" || s.connection === "failed" || this.#closed)
+        else if (s.connection === "closed" || this.#closed)
             d.reject(new SynapseError("not_connected", "the node ended before the view got a value"));
     }
     /** Resolves with the state after the next change; a closed view resolves with its final state. */
@@ -58,13 +58,15 @@ export class TopicView {
         this.#changed = undefined;
         c?.resolve(this.#state);
     }
-    /** Called on every state change; the returned function removes the listener. */
-    subscribe(listener) {
+    /** `cb` with the state on every change; the returned function removes it. Told once more when the view closes. */
+    onChange(cb) {
         if (this.#closed)
             return () => { };
-        this.#listeners.add(listener);
-        return () => { this.#listeners.delete(listener); };
+        this.#listeners.add(cb);
+        return () => { this.#listeners.delete(cb); };
     }
+    /** The state after each change; ends when the view is closed or the node ends. */
+    watch() { return watchState(cb => this.onChange(cb), () => this.#state, () => this.#closed || this.node.isEnded); }
     async #read() {
         for (;;) {
             const batch = await this.#sub.next();
@@ -121,11 +123,11 @@ export class TopicView {
             return;
         this.#state = { ...s, ...patch };
         for (const l of [...this.#listeners])
-            l();
+            l(this.#state);
         this.#settleChanged();
         this.#settleReady();
     }
-    /** Ends the view for good: the subscription is closed, listeners are dropped, waiters settle, the registry entry is released. */
+    /** Ends the view for good: the subscription is closed, listeners are told once and dropped, waiters settle, the registry entry is released. */
     close() {
         if (this.#closed)
             return;
@@ -136,7 +138,16 @@ export class TopicView {
             clearTimeout(this.#staleTimer);
             this.#staleTimer = undefined;
         }
+        const ls = [...this.#listeners];
         this.#listeners.clear();
+        for (const l of ls) {
+            try {
+                l(this.#state);
+            }
+            catch (e) {
+                queueMicrotask(() => { throw e; });
+            }
+        }
         this.#settleChanged();
         this.#settleReady();
         this.onClose();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,7 +14,7 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.0",
+    "@synapse-sdk/core": "0.3.4",
     "@moq/net": "0.4.2"
   },
   "peerDependencies": {