@synapse-sdk/client 0.1.0 → 0.3.3

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,67 @@
+export interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (v: T | PromiseLike<T>) => void;
+    reject: (e: unknown) => void;
+    settled: boolean;
+}
+export declare function deferred<T>(): Deferred<T>;
+/** A value plus listeners. `changed()` resolves on the next `set`. */
+export declare class Cell<T> {
+    #private;
+    constructor(v: T);
+    get(): T;
+    set(v: T): void;
+    update(f: (v: T) => T): void;
+    subscribe(l: (v: T) => void): () => void;
+    changed(): Promise<T>;
+    get listenerCount(): number;
+}
+export declare const DONE: unique symbol;
+/**
+ * Bounded FIFO with one consumer. `push` never blocks: past `capacity` the oldest item is dropped
+ * and `onDrop` is told (`capacity` `Infinity`: unbounded, nothing is dropped). `close()` ends the
+ * stream after buffered items; `close(true)` discards them.
+ */
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    #private;
+    capacity: number;
+    private readonly onDrop?;
+    constructor(capacity: number, onDrop?: ((dropped: T) => void) | undefined);
+    get size(): number;
+    get closed(): boolean;
+    push(v: T): boolean;
+    /**
+     * Backpressure form: waits while the queue is full instead of dropping, so a reader that awaits
+     * it stops taking from the transport (QUIC flow control then pushes back on the publisher).
+     * Resolves `false` when the queue is closed meanwhile.
+     */
+    pushWhenRoom(v: T): Promise<boolean>;
+    pull(): Promise<T | typeof DONE>;
+    /**
+     * `pull()` as `undefined` at the end. A `next()` that is waiting receives the next pushed item
+     * (it is not buffered): a caller that races `next()` against something else and loses must keep
+     * that promise and use it later, or the item it receives is lost.
+     */
+    next(): Promise<T | undefined>;
+    /** An item already queued, without waiting. */
+    tryNext(): T | undefined;
+    /** Ends the queue. Buffered items are still delivered unless `discard`. Resolves when drained. */
+    close(discard?: boolean): Promise<void>;
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, undefined>;
+}
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare const TIMEOUT: unique symbol;
+/** Races `p` against a timeout; resolves to TIMEOUT instead of throwing so callers can branch. */
+export declare function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMEOUT>;
+export declare function nowMs(): number;
+/** Keeps `prev` references wherever `next` is deep-equal to them (TanStack Query's replaceEqualDeep). */
+export declare function replaceEqualDeep<T>(prev: unknown, next: T): T;
+export declare function shallowEqual(a: unknown, b: unknown): boolean;
+/** Percentile over a small ring of samples. */
+export declare class Ring {
+    #private;
+    private readonly cap;
+    constructor(cap?: number);
+    push(v: number): void;
+    percentile(p: number): number | undefined;
+}

package/dist/util.js

@@ -0,0 +1,227 @@
+// Small primitives shared by the client: a value cell with change notification, a bounded async
+// queue, deferreds, sleeps that honour AbortSignals, and TanStack-style structural sharing.
+export function deferred() {
+    const d = { settled: false };
+    d.promise = new Promise((res, rej) => {
+        d.resolve = v => { d.settled = true; res(v); };
+        d.reject = e => { d.settled = true; rej(e); };
+    });
+    return d;
+}
+/** A value plus listeners. `changed()` resolves on the next `set`. */
+export class Cell {
+    #v;
+    #listeners = new Set();
+    #waiters;
+    constructor(v) { this.#v = v; }
+    get() { return this.#v; }
+    set(v) {
+        this.#v = v;
+        const w = this.#waiters;
+        this.#waiters = undefined;
+        w?.resolve(v);
+        for (const l of [...this.#listeners]) {
+            try {
+                l(v);
+            }
+            catch (e) {
+                queueMicrotask(() => { throw e; });
+            }
+        }
+    }
+    update(f) { this.set(f(this.#v)); }
+    subscribe(l) { this.#listeners.add(l); return () => { this.#listeners.delete(l); }; }
+    changed() { this.#waiters ??= deferred(); return this.#waiters.promise; }
+    get listenerCount() { return this.#listeners.size; }
+}
+export const DONE = Symbol("done");
+/**
+ * Bounded FIFO with one consumer. `push` never blocks: past `capacity` the oldest item is dropped
+ * and `onDrop` is told (`capacity` `Infinity`: unbounded, nothing is dropped). `close()` ends the
+ * stream after buffered items; `close(true)` discards them.
+ */
+export class AsyncQueue {
+    capacity;
+    onDrop;
+    #items = [];
+    #waiter;
+    #closed = false;
+    #drained;
+    constructor(capacity, onDrop) {
+        this.capacity = capacity;
+        this.onDrop = onDrop;
+    }
+    get size() { return this.#items.length; }
+    get closed() { return this.#closed; }
+    push(v) {
+        if (this.#closed)
+            return false;
+        if (this.#waiter) {
+            const w = this.#waiter;
+            this.#waiter = undefined;
+            w.resolve(v);
+            return true;
+        }
+        if (this.#items.length >= this.capacity) {
+            const d = this.#items.shift();
+            this.onDrop?.(d);
+        }
+        this.#items.push(v);
+        return true;
+    }
+    /**
+     * Backpressure form: waits while the queue is full instead of dropping, so a reader that awaits
+     * it stops taking from the transport (QUIC flow control then pushes back on the publisher).
+     * Resolves `false` when the queue is closed meanwhile.
+     */
+    async pushWhenRoom(v) {
+        while (!this.#closed && !this.#waiter && this.#items.length >= this.capacity) {
+            this.#room ??= deferred();
+            await this.#room.promise;
+        }
+        return this.push(v);
+    }
+    #room;
+    #signalRoom() { if (this.#room) {
+        const r = this.#room;
+        this.#room = undefined;
+        r.resolve();
+    } }
+    pull() {
+        if (this.#items.length) {
+            const v = this.#items.shift();
+            this.#signalRoom();
+            if (this.#closed && this.#items.length === 0)
+                this.#drained?.resolve();
+            return Promise.resolve(v);
+        }
+        if (this.#closed)
+            return Promise.resolve(DONE);
+        this.#waiter ??= deferred();
+        return this.#waiter.promise;
+    }
+    /**
+     * `pull()` as `undefined` at the end. A `next()` that is waiting receives the next pushed item
+     * (it is not buffered): a caller that races `next()` against something else and loses must keep
+     * that promise and use it later, or the item it receives is lost.
+     */
+    next() { return this.pull().then(v => (v === DONE ? undefined : v)); }
+    /** An item already queued, without waiting. */
+    tryNext() {
+        if (!this.#items.length)
+            return undefined;
+        const v = this.#items.shift();
+        this.#signalRoom();
+        if (this.#closed && this.#items.length === 0)
+            this.#drained?.resolve();
+        return v;
+    }
+    /** Ends the queue. Buffered items are still delivered unless `discard`. Resolves when drained. */
+    close(discard = false) {
+        if (discard)
+            this.#items.length = 0;
+        this.#closed = true;
+        this.#signalRoom();
+        if (this.#waiter) {
+            const w = this.#waiter;
+            this.#waiter = undefined;
+            w.resolve(DONE);
+        }
+        if (this.#items.length === 0)
+            return Promise.resolve();
+        this.#drained ??= deferred();
+        return this.#drained.promise;
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            const v = await this.pull();
+            if (v === DONE)
+                return;
+            yield v;
+        }
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const t = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, ms);
+        const onAbort = () => { clearTimeout(t); reject(signal.reason); };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export const TIMEOUT = Symbol("timeout");
+/** Races `p` against a timeout; resolves to TIMEOUT instead of throwing so callers can branch. */
+export function withTimeout(p, ms) {
+    let t;
+    return Promise.race([p.finally(() => clearTimeout(t)), new Promise(r => { t = setTimeout(() => r(TIMEOUT), ms); })]);
+}
+export function nowMs() { return performance.now(); }
+/** Keeps `prev` references wherever `next` is deep-equal to them (TanStack Query's replaceEqualDeep). */
+export function replaceEqualDeep(prev, next) {
+    if (prev === next)
+        return next;
+    const pa = Array.isArray(prev), na = Array.isArray(next);
+    if (pa && na) {
+        const p = prev, n = next;
+        let equal = p.length === n.length;
+        const out = new Array(n.length);
+        for (let i = 0; i < n.length; i++) {
+            out[i] = replaceEqualDeep(p[i], n[i]);
+            if (out[i] !== p[i])
+                equal = false;
+        }
+        return (equal ? prev : out);
+    }
+    if (!pa && !na && isPlainObject(prev) && isPlainObject(next)) {
+        const p = prev, n = next;
+        const nk = Object.keys(n);
+        const pk = Object.keys(p);
+        let equal = nk.length === pk.length;
+        const out = {};
+        for (const k of nk) {
+            out[k] = replaceEqualDeep(p[k], n[k]);
+            if (out[k] !== p[k] || !(k in p))
+                equal = false;
+        }
+        return (equal ? prev : out);
+    }
+    return next;
+}
+function isPlainObject(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+export function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || typeof a !== "object" || typeof b !== "object")
+        return false;
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    for (const k of ka)
+        if (a[k] !== b[k])
+            return false;
+    return true;
+}
+/** Percentile over a small ring of samples. */
+export class Ring {
+    cap;
+    #buf = [];
+    constructor(cap = 512) {
+        this.cap = cap;
+    }
+    push(v) { if (this.#buf.length >= this.cap)
+        this.#buf.shift(); this.#buf.push(v); }
+    percentile(p) {
+        if (!this.#buf.length)
+            return undefined;
+        const s = [...this.#buf].sort((a, b) => a - b);
+        return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))];
+    }
+}

package/dist/view.d.ts

@@ -0,0 +1,19 @@
+import type { Node } from "./node.ts";
+import type { Subscription, View, ViewOptions, ViewState } from "./types.ts";
+export declare class TopicView<T, S> implements View<S> {
+    #private;
+    private readonly node;
+    private readonly opts;
+    private readonly onClose;
+    constructor(node: Node, open: () => Subscription<T>, opts: ViewOptions<T, S>, onClose: () => void);
+    get(): ViewState<S>;
+    /** Resolves on the first value; `not_connected` if the node ends (or the view is closed) first. */
+    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. */
+    close(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/view.js

@@ -0,0 +1,145 @@
+// 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
+// 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";
+export class TopicView {
+    node;
+    opts;
+    onClose;
+    #state;
+    #listeners = new Set();
+    #sub;
+    #staleTimer;
+    #unwatchLink;
+    #ready;
+    #changed;
+    #closed = false;
+    constructor(node, open, opts, onClose) {
+        this.node = node;
+        this.opts = opts;
+        this.onClose = onClose;
+        this.#state = { data: undefined, status: "pending", connection: node.state().status, lastChangeAtUs: undefined };
+        this.#sub = open();
+        this.#unwatchLink = node.link.subscribe(() => this.#set({ connection: node.state().status }));
+        void this.#read();
+    }
+    get() { return this.#state; }
+    /** Resolves on the first value; `not_connected` if the node ends (or the view is closed) first. */
+    ready() {
+        if (!this.#ready) {
+            this.#ready = deferred();
+            this.#ready.promise.catch(() => { });
+            this.#settleReady();
+        }
+        return this.#ready.promise;
+    }
+    #settleReady() {
+        const d = this.#ready;
+        if (!d || d.settled)
+            return;
+        const s = this.#state;
+        if (s.status === "live" || s.status === "stale")
+            d.resolve();
+        else if (s.connection === "closed" || s.connection === "failed" || 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. */
+    changed() {
+        if (this.#closed)
+            return Promise.resolve(this.#state);
+        this.#changed ??= deferred();
+        return this.#changed.promise;
+    }
+    #settleChanged() {
+        const c = this.#changed;
+        this.#changed = undefined;
+        c?.resolve(this.#state);
+    }
+    /** Called on every state change; the returned function removes the listener. */
+    subscribe(listener) {
+        if (this.#closed)
+            return () => { };
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    async #read() {
+        for (;;) {
+            const batch = await this.#sub.next();
+            if (!batch) {
+                if (!this.#closed)
+                    this.#set({ connection: this.node.state().status });
+                return;
+            }
+            if (this.#closed)
+                return;
+            let newest = batch[0];
+            for (const e of batch)
+                if (e.tUs > newest.tUs)
+                    newest = e;
+            this.#onData(newest);
+        }
+    }
+    #onData(env) {
+        let selected;
+        try {
+            selected = this.opts.select ? this.opts.select(env.data) : env.data;
+        }
+        catch (e) {
+            queueMicrotask(() => { throw e; });
+            return;
+        }
+        const prev = this.#state.data;
+        const next = replaceEqualDeep(prev, selected);
+        // `staleTime` counts from the value's own stamp when the publisher is in our time domain, else from arrival.
+        let staleInMs;
+        if (this.opts.staleTime !== undefined) {
+            const ageUs = env.dom === this.node.dom.id ? Math.max(0, this.node.currentSession()?.nowUs() ?? 0) - env.tUs : 0;
+            staleInMs = this.opts.staleTime - ageUs / 1000;
+        }
+        const status = staleInMs !== undefined && staleInMs <= 0 ? "stale" : "live";
+        if (next !== prev || this.#state.status !== status)
+            this.#set({ data: next, status, lastChangeAtUs: env.tUs });
+        if (this.#staleTimer !== undefined) {
+            clearTimeout(this.#staleTimer);
+            this.#staleTimer = undefined;
+        }
+        if (staleInMs !== undefined && staleInMs > 0)
+            this.#staleTimer = setTimeout(() => { this.#staleTimer = undefined; this.#set({ status: "stale" }); }, staleInMs);
+    }
+    #set(patch) {
+        const s = this.#state;
+        let changed = false;
+        for (const k of Object.keys(patch))
+            if (s[k] !== patch[k]) {
+                changed = true;
+                break;
+            }
+        if (!changed)
+            return;
+        this.#state = { ...s, ...patch };
+        for (const l of [...this.#listeners])
+            l();
+        this.#settleChanged();
+        this.#settleReady();
+    }
+    /** Ends the view for good: the subscription is closed, listeners are dropped, waiters settle, the registry entry is released. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#sub.unsubscribe();
+        this.#unwatchLink();
+        if (this.#staleTimer !== undefined) {
+            clearTimeout(this.#staleTimer);
+            this.#staleTimer = undefined;
+        }
+        this.#listeners.clear();
+        this.#settleChanged();
+        this.#settleReady();
+        this.onClose();
+    }
+    async [Symbol.asyncDispose]() { this.close(); }
+}

package/package.json

@@ -1,57 +1,36 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.1.0",
+  "version": "0.3.3",
+  "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
-  "description": "Isomorphic TypeScript SDK for the Synapse robotics bus (Phoenix Channels).",
-  "license": "UNLICENSED",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./react": {
-      "types": "./dist/react.d.ts",
-      "import": "./dist/react.js"
+      "default": "./dist/index.js"
     }
   },
-  "files": ["dist"],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsdown src/index.ts src/react.tsx --platform neutral --dts",
-    "prepare": "tsdown src/index.ts src/react.tsx --platform neutral --dts",
-    "test": "bun test",
-    "typecheck": "tsc --noEmit"
-  },
-  "publishConfig": {
-    "access": "restricted"
-  },
+  "files": [
+    "dist"
+  ],
   "dependencies": {
-    "phoenix": "^1.8.8"
+    "@synapse-sdk/core": "0.3.3",
+    "@moq/net": "0.4.2"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "@moq/web-transport": "0.1.5"
   },
   "peerDependenciesMeta": {
-    "react": {
+    "@moq/web-transport": {
       "optional": true
     }
   },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.2",
-    "@testing-library/dom": "^10.4.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/bun": "latest",
-    "@types/phoenix": "^1.6.7",
-    "@types/react": "^19.2.17",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "tsdown": "^0.22.2",
-    "typescript": "^5"
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taiga-robotics/synapse"
   }
 }