@synapse-sdk/react 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @synapse-sdk/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of the Synapse SDK for JavaScript. Documentation: the repository.

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+import { type ReactNode } from "react";
+import type { Synapse, Catalog, ConnectionState, Notice, ViewOptions, ViewState, Run, CallOptions, Publisher, ServeHandler, ServeOptions, Registration, StoreHandle, StoreOptions, SceneEntity, SceneEntityLive, SceneHandle, SceneStatus, SceneTree } from "@synapse-sdk/client";
+import type { ErrorBody, ProjectSnapshot, ServiceRef, TopicRef, SynapseError } from "@synapse-sdk/core";
+export declare function SynapseProvider({ node, children }: {
+    node: Synapse;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Synapse | null>>;
+export declare function useSynapse(): Synapse;
+/** The node from the nearest `<SynapseProvider>`, or `null` when there is none. */
+export declare function useSynapseOptional(): Synapse | null;
+/** The node's `ConnectionState`; a `setTarget` switch shows as `connecting` → `connected` with the new `url`. */
+export declare function useConnection(): ConnectionState;
+/** The runtime's project state (`node.project()`, WP §3.5); `undefined` between sessions or before the first snapshot. */
+export declare function useProject(): ProjectSnapshot | undefined;
+/** The runtime's catalogs as the current session last read them. */
+export declare function useCatalog(): Catalog;
+/** The last `limit` broker notices (`node.onNotice`) since the component mounted, newest last. */
+export declare function useNotices(limit?: number): ErrorBody[];
+/** The last `limit` `promoted`/`demoted` notices since the component mounted, newest last. */
+export declare function useProjectNotices(limit?: number): Notice[];
+/** Typed disabled sentinel: `useTopic("skip")` renders `pending` without subscribing. */
+export type Skip = "skip";
+/**
+ * A topic's value now (SDK §8). The view is made when the component mounts and closed when it
+ * unmounts (a view is subscribed for its whole life, like the Rust one; StrictMode's mount → unmount →
+ * mount makes a second view and closes the first). It is made again only when the topic or an option
+ * other than `select` changes. `select` runs here, over the view's value, with the selector of the
+ * latest render (so values it captures are current); a selected value deep-equal to the previous one
+ * keeps its reference.
+ */
+export declare function useTopic<TOut, S = TOut>(topic: TopicRef<unknown, TOut> | Skip, opts?: ViewOptions<TOut, S>): ViewState<S>;
+/** TanStack's mutation vocabulary (`useMutation().status`); the protocol's `RunStatus` lives on `run.status`. */
+export type CallStatus = "idle" | "pending" | "success" | "error";
+/** A request/reply call as a mutation: `call(args)` returns the result; `status`/`data`/`error` follow the latest call. */
+export declare function useCall<A, R>(svc: ServiceRef<A, unknown, unknown, R>, opts?: CallOptions<unknown>): {
+    call: (args: A) => Promise<R>;
+    reset(): void;
+    status: CallStatus;
+    data?: R;
+    error?: SynapseError;
+};
+export interface UseStartOptions<U> extends CallOptions<U> {
+    /** How many progress updates `updates` keeps (newest last); default 100. `latestUpdate` is always the newest. */
+    maxUpdates?: number;
+}
+/**
+ * `start()` a streaming call from a component. `status` is TanStack's (`pending` covers the spec's
+ * `pending` and `running`; `error` covers `failed` and `canceled` — `run.status` and `error.code`
+ * tell which). The run in flight is canceled with reason `"unmount"` when the component unmounts.
+ */
+export declare function useStart<A, U, R>(svc: ServiceRef<A, unknown, U, R>, opts?: UseStartOptions<U>): {
+    start: (args: A) => Run<U, R>;
+    cancel: (reason?: string) => Promise<void>;
+    run: Run<U, R> | undefined;
+    status: CallStatus;
+    updates: U[];
+    latestUpdate: U;
+    result: R | undefined;
+    error: SynapseError | undefined;
+};
+/** Registers a provider on mount and unregisters on unmount (see `acquireLease`). The handler may change between renders. */
+export declare function useServe<I, U, R>(svc: ServiceRef<I, I, U, R>, handler: ServeHandler<I, U, R>, opts?: ServeOptions): {
+    ready: boolean;
+    error?: SynapseError;
+    registration?: Registration;
+};
+/** A publisher held for the component's life: `publish` drops (and counts) until it is admitted. */
+export declare function usePublisher<TIn>(topic: TopicRef<TIn, unknown>): {
+    publish: (v: TIn) => void;
+    ready: boolean;
+    error?: SynapseError;
+    publisher?: Publisher<TIn>;
+};
+/**
+ * A namespace as a value: `const [board, handle] = useStore("mission/board", { access: "public" })` — `board` re-renders on
+ * every change (the same object while nothing changed); `handle` for `set`/`delete`/`status`. `handle` is `null` until the
+ * open resolved (the value is `{}` then); an open refused for good (`project_inactive`) is in `error`.
+ */
+export declare function useStore(name: string, opts?: StoreOptions): readonly [Record<string, unknown>, StoreHandle | null, SynapseError | undefined];
+/**
+ * The active project's scene for the component's life: `[scene, error]`. `scene` is `null` until
+ * `node.scene()` resolved; it is closed when the component unmounts.
+ */
+export declare function useScene(): readonly [SceneHandle | null, SynapseError | undefined];
+/**
+ * One entity of the scene (`scene.entity(id, { plane })`): the merged entity (or, with `plane`, that
+ * layer's value alone: `authored` or `live`), or what `select` picks from it (`select` gets
+ * `undefined` while there is none). The view reads the handle's copy
+ * of the scene and follows it only while the component is subscribed. `select` runs here with the
+ * selector of the latest render; a selected value deep-equal to the previous one keeps its reference,
+ * so a live pose that does not change what `select` picks does not re-render the component.
+ */
+export declare function useSceneEntity<S = SceneEntity | undefined>(scene: SceneHandle | null | undefined, id: string | null | undefined, opts?: {
+    plane?: "authored";
+    select?: (e: SceneEntity | undefined) => S;
+}): S;
+export declare function useSceneEntity<S = SceneEntityLive | undefined>(scene: SceneHandle | null | undefined, id: string | null | undefined, opts: {
+    plane: "live";
+    select?: (e: SceneEntityLive | undefined) => S;
+}): S;
+/** The scene's hierarchy (`scene.tree()`), as its roots: the same array while the structure does not change; empty without a scene. */
+export declare function useSceneTree(scene: SceneHandle | null | undefined): SceneTree;
+/** The scene handle's status (`scene.status`), re-rendering when a field changes; `undefined` without a scene. */
+export declare function useSceneStatus(scene: SceneHandle | null | undefined): SceneStatus | undefined;

package/dist/index.js

@@ -0,0 +1,373 @@
+// @synapse-sdk/react: thin hooks over the client's cells (SDK §8). No wrapper state: every hook reads
+// through useSyncExternalStore from a client object (a view, a store handle, the node's link).
+//
+// Statuses speak TanStack here (`idle | pending | success | error`, like `useMutation`); the spec's
+// five-state `RunStatus` stays on the `Run` the hooks hand back. One rule, two layers.
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { replaceEqualDeep, shallowEqual } from "@synapse-sdk/client";
+import { toSynapseError } from "@synapse-sdk/core";
+const SynapseContext = createContext(null);
+export function SynapseProvider({ node, children }) {
+    return createElement(SynapseContext.Provider, { value: node }, children);
+}
+export function useSynapse() {
+    const node = useContext(SynapseContext);
+    if (!node)
+        throw new Error("useSynapse: no <SynapseProvider> above this component");
+    return node;
+}
+/** The node from the nearest `<SynapseProvider>`, or `null` when there is none. */
+export function useSynapseOptional() { return useContext(SynapseContext); }
+/** The node's `ConnectionState`; a `setTarget` switch shows as `connecting` → `connected` with the new `url`. */
+export function useConnection() {
+    const node = useSynapse();
+    // `node.status` builds a new object on every read; React needs the same object while nothing
+    // changed, so the last one read is kept and handed back while every field is the same.
+    const last = useRef(undefined);
+    const get = useCallback(() => {
+        const s = node.status;
+        if (!shallowEqual(last.current, s))
+            last.current = s;
+        return last.current;
+    }, [node]);
+    return useSyncExternalStore(useCallback((cb) => node.watchStatus(() => cb()), [node]), get, get);
+}
+/** The runtime's project state (`node.project()`, WP §3.5); `undefined` between sessions or before the first snapshot. */
+export function useProject() {
+    const node = useSynapse();
+    return useSyncExternalStore(useCallback((cb) => node.watchProject(() => cb()), [node]), () => node.project(), () => node.project());
+}
+/** The runtime's catalogs as the current session last read them. */
+export function useCatalog() {
+    const node = useSynapse();
+    const ref = useRef(node.catalog);
+    return useSyncExternalStore(useCallback((cb) => node.watchCatalog(c => { ref.current = c; cb(); }), [node]), () => ref.current, () => ref.current);
+}
+/** The last `limit` broker notices (`node.onNotice`) since the component mounted, newest last. */
+export function useNotices(limit = 20) {
+    const node = useSynapse();
+    const [list, setList] = useState([]);
+    useEffect(() => node.onNotice(n => setList(l => [...l, n].slice(-limit))), [node, limit]);
+    return list;
+}
+/** The last `limit` `promoted`/`demoted` notices since the component mounted, newest last. */
+export function useProjectNotices(limit = 20) {
+    const node = useSynapse();
+    const [list, setList] = useState([]);
+    useEffect(() => node.onProjectNotice(n => setList(l => [...l, n].slice(-limit))), [node, limit]);
+    return list;
+}
+const SKIP_STATE = { data: undefined, status: "pending", connection: "connecting", lastChangeAtUs: undefined };
+/**
+ * A topic's value now (SDK §8). The view is made when the component mounts and closed when it
+ * unmounts (a view is subscribed for its whole life, like the Rust one; StrictMode's mount → unmount →
+ * mount makes a second view and closes the first). It is made again only when the topic or an option
+ * other than `select` changes. `select` runs here, over the view's value, with the selector of the
+ * latest render (so values it captures are current); a selected value deep-equal to the previous one
+ * keeps its reference.
+ */
+export function useTopic(topic, opts = {}) {
+    const node = useSynapse();
+    const { select, ...viewOpts } = opts;
+    const selectRef = useRef(select);
+    selectRef.current = select;
+    const key = JSON.stringify([typeof topic === "string" ? topic : topic.name, viewOpts]);
+    const topicRef = useRef(topic);
+    topicRef.current = topic;
+    const optsRef = useRef(viewOpts);
+    optsRef.current = viewOpts;
+    const [view, setView] = useState(undefined);
+    useEffect(() => {
+        const t = topicRef.current;
+        if (t === "skip") {
+            setView(undefined);
+            return;
+        }
+        const v = node.view(t, optsRef.current);
+        setView(v);
+        return () => { v.close(); };
+    }, [node, key]);
+    const subscribe = useCallback((cb) => (view ? view.subscribe(cb) : () => { }), [view]);
+    // The last result, with what it was made from: the same view state and selector give it back unchanged.
+    const last = useRef(undefined);
+    const get = useCallback(() => {
+        if (!view)
+            return SKIP_STATE;
+        const from = view.get();
+        const sel = selectRef.current;
+        if (!sel)
+            return from;
+        const prev = last.current;
+        if (prev && prev.from === from && prev.select === sel)
+            return prev.out;
+        const data = from.data === undefined ? undefined : replaceEqualDeep(prev?.out.data, sel(from.data));
+        const out = prev && shallowEqual(prev.out, { ...from, data }) ? prev.out : { ...from, data };
+        last.current = { from, select: sel, out };
+        return out;
+    }, [view]);
+    return useSyncExternalStore(subscribe, get, get);
+}
+/** A service as a name: what the hooks key their memoisation on, so an inline contract (a new object every render) is fine. */
+function nameOf(svc) { return typeof svc === "string" ? svc : svc.name; }
+/** A request/reply call as a mutation: `call(args)` returns the result; `status`/`data`/`error` follow the latest call. */
+export function useCall(svc, opts = {}) {
+    const node = useSynapse();
+    const [state, setState] = useState({ status: "idle" });
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const svcRef = useRef(svc);
+    svcRef.current = svc;
+    const name = nameOf(svc);
+    const seq = useRef(0);
+    const call = useCallback(async (args) => {
+        const my = ++seq.current;
+        setState(s => ({ ...s, status: "pending", error: undefined }));
+        try {
+            const r = await node.call(svcRef.current, args, optsRef.current).result;
+            if (my === seq.current)
+                setState({ status: "success", data: r });
+            return r;
+        }
+        catch (e) {
+            const err = toSynapseError(e);
+            if (my === seq.current)
+                setState(s => ({ ...s, status: "error", error: err }));
+            throw err;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [node, name]);
+    const reset = useCallback(() => { seq.current++; setState({ status: "idle" }); }, []);
+    return { call, reset, ...state };
+}
+/**
+ * `start()` a streaming call from a component. `status` is TanStack's (`pending` covers the spec's
+ * `pending` and `running`; `error` covers `failed` and `canceled` — `run.status` and `error.code`
+ * tell which). The run in flight is canceled with reason `"unmount"` when the component unmounts.
+ */
+export function useStart(svc, opts = {}) {
+    const node = useSynapse();
+    const [run, setRun] = useState(undefined);
+    const [status, setStatus] = useState("idle");
+    const [updates, setUpdates] = useState([]);
+    const [result, setResult] = useState(undefined);
+    const [error, setError] = useState(undefined);
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const svcRef = useRef(svc);
+    svcRef.current = svc;
+    const runRef = useRef(undefined);
+    const name = nameOf(svc);
+    const start = useCallback((args) => {
+        const { maxUpdates = 100, ...callOpts } = optsRef.current;
+        const keep = Math.max(1, maxUpdates);
+        const r = node.call(svcRef.current, args, { ...callOpts, onUpdate: u => { if (runRef.current === r)
+                setUpdates(prev => (prev.length < keep ? [...prev, u] : [...prev.slice(prev.length - keep + 1), u])); optsRef.current.onUpdate?.(u); } });
+        runRef.current = r;
+        setRun(r);
+        setStatus("pending");
+        setUpdates([]);
+        setResult(undefined);
+        setError(undefined);
+        r.result.then(v => { if (runRef.current === r) {
+            setResult(v);
+            setStatus("success");
+        } }, e => { if (runRef.current === r) {
+            setError(toSynapseError(e));
+            setStatus("error");
+        } });
+        return r;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [node, name]);
+    const cancel = useCallback((reason) => runRef.current?.cancel(reason) ?? Promise.resolve(), []);
+    useEffect(() => () => { const r = runRef.current; runRef.current = undefined; void r?.cancel("unmount"); }, []);
+    return { start, cancel, run, status, updates, latestUpdate: updates[updates.length - 1], result, error };
+}
+const leases = new WeakMap();
+function acquireLease(node, svc, handler, opts) {
+    let byName = leases.get(node);
+    if (!byName) {
+        byName = new Map();
+        leases.set(node, byName);
+    }
+    const name = nameOf(svc);
+    let lease = byName.get(name);
+    if (lease) {
+        if (lease.release !== undefined) {
+            clearTimeout(lease.release);
+            lease.release = undefined;
+        }
+        lease.users++;
+        lease.handler = handler;
+        return lease;
+    }
+    const l = { reg: undefined, handler, users: 1 };
+    l.reg = node.serve(svc, (input, ctx) => l.handler(input, ctx), opts);
+    l.reg.catch(() => { });
+    byName.set(name, l);
+    return l;
+}
+function releaseLease(node, name, lease) {
+    lease.users--;
+    if (lease.users > 0)
+        return;
+    lease.release = setTimeout(() => {
+        lease.release = undefined;
+        if (lease.users > 0)
+            return;
+        const byName = leases.get(node);
+        if (byName?.get(name) === lease)
+            byName.delete(name);
+        void lease.reg.then(r => r.unregister(), () => { });
+    }, 0);
+}
+/** Registers a provider on mount and unregisters on unmount (see `acquireLease`). The handler may change between renders. */
+export function useServe(svc, handler, opts = {}) {
+    const node = useSynapse();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const svcRef = useRef(svc);
+    svcRef.current = svc;
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const [state, setState] = useState({ ready: false });
+    const name = nameOf(svc);
+    useEffect(() => {
+        const lease = acquireLease(node, svcRef.current, (input, ctx) => handlerRef.current(input, ctx), optsRef.current);
+        let mine = true;
+        lease.reg.then(reg => { if (mine)
+            setState({ ready: true, registration: reg }); }, e => { if (mine)
+            setState({ ready: false, error: toSynapseError(e) }); });
+        return () => { mine = false; releaseLease(node, name, lease); };
+    }, [node, name]);
+    return state;
+}
+/** A publisher held for the component's life: `publish` drops (and counts) until it is admitted. */
+export function usePublisher(topic) {
+    const node = useSynapse();
+    const name = typeof topic === "string" ? topic : topic.name;
+    const topicRef = useRef(topic);
+    topicRef.current = topic;
+    const [state, setState] = useState({ ready: false });
+    const pubRef = useRef(undefined);
+    useEffect(() => {
+        let mine = true;
+        let pub;
+        node.publisher(topicRef.current).then(p => { if (!mine) {
+            p.close();
+            return;
+        } pub = p; pubRef.current = p; setState({ ready: true, publisher: p }); }, e => { if (mine)
+            setState({ ready: false, error: toSynapseError(e) }); });
+        return () => { mine = false; pub?.close(); if (pubRef.current === pub)
+            pubRef.current = undefined; };
+    }, [node, name]);
+    const publish = useCallback((v) => { pubRef.current?.publish(v); }, []);
+    return { publish, ...state };
+}
+/**
+ * A namespace as a value: `const [board, handle] = useStore("mission/board", { access: "public" })` — `board` re-renders on
+ * every change (the same object while nothing changed); `handle` for `set`/`delete`/`status`. `handle` is `null` until the
+ * open resolved (the value is `{}` then); an open refused for good (`project_inactive`) is in `error`.
+ */
+export function useStore(name, opts = {}) {
+    const node = useSynapse();
+    const key = JSON.stringify([name, opts.access, opts.onDeath]);
+    const [handle, setHandle] = useState(null);
+    const [error, setError] = useState(undefined);
+    useEffect(() => {
+        let mine = true;
+        let h;
+        setHandle(null);
+        setError(undefined);
+        node.store(name, opts).then(s => { if (!mine) {
+            s.close();
+            return;
+        } h = s; setHandle(s); }, e => { if (mine)
+            setError(toSynapseError(e)); });
+        return () => { mine = false; h?.close(); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [node, key]);
+    const subscribe = useCallback((cb) => (handle ? handle.subscribe(cb) : () => { }), [handle]);
+    // React re-renders when the snapshot changes: it holds the value and the handle's status, so a
+    // change of `synced`/`pending`/`connected` alone re-renders too (the component reads them on
+    // `handle`). `handle.status` builds a new object on every read, so the snapshot is rebuilt only
+    // when the value or a status field differs.
+    const last = useRef(undefined);
+    const get = useCallback(() => {
+        if (!handle)
+            return undefined;
+        const value = handle.value, status = handle.status;
+        const prev = last.current;
+        if (!prev || prev.handle !== handle || prev.value !== value || !shallowEqual(prev.status, status))
+            last.current = { handle, value, status };
+        return last.current;
+    }, [handle]);
+    const snap = useSyncExternalStore(subscribe, get, get);
+    return [snap ? snap.value : EMPTY, handle, error];
+}
+const EMPTY = {};
+/**
+ * The active project's scene for the component's life: `[scene, error]`. `scene` is `null` until
+ * `node.scene()` resolved; it is closed when the component unmounts.
+ */
+export function useScene() {
+    const node = useSynapse();
+    const [scene, setScene] = useState(null);
+    const [error, setError] = useState(undefined);
+    useEffect(() => {
+        let mine = true;
+        let h;
+        setScene(null);
+        setError(undefined);
+        node.scene().then(s => { if (!mine) {
+            s.close();
+            return;
+        } h = s; setScene(s); }, e => { if (mine)
+            setError(toSynapseError(e)); });
+        return () => { mine = false; h?.close(); };
+    }, [node]);
+    return [scene, error];
+}
+export function useSceneEntity(scene, id, opts = {}) {
+    const selectRef = useRef(opts.select);
+    selectRef.current = opts.select;
+    const plane = opts.plane;
+    const view = useMemo(() => (scene && id ? scene.entity(id, plane ? { plane } : undefined) : undefined), [scene, id, plane]);
+    const subscribe = useCallback((cb) => (view ? view.subscribe(cb) : () => { }), [view]);
+    const last = useRef(undefined);
+    const get = useCallback(() => {
+        const from = view?.get();
+        const sel = selectRef.current;
+        if (!sel)
+            return from;
+        const prev = last.current;
+        if (prev && prev.from === from && prev.select === sel)
+            return prev.out;
+        const out = replaceEqualDeep(prev?.out, sel(from));
+        last.current = { from, select: sel, out };
+        return out;
+    }, [view]);
+    return useSyncExternalStore(subscribe, get, get);
+}
+const EMPTY_TREE = [];
+/** The scene's hierarchy (`scene.tree()`), as its roots: the same array while the structure does not change; empty without a scene. */
+export function useSceneTree(scene) {
+    const view = useMemo(() => scene?.tree(), [scene]);
+    const subscribe = useCallback((cb) => (view ? view.subscribe(cb) : () => { }), [view]);
+    const get = useCallback(() => view?.get() ?? EMPTY_TREE, [view]);
+    return useSyncExternalStore(subscribe, get, get);
+}
+/** The scene handle's status (`scene.status`), re-rendering when a field changes; `undefined` without a scene. */
+export function useSceneStatus(scene) {
+    // `scene.status` builds a new object on every read: the last one is kept while every field is the same.
+    const last = useRef(undefined);
+    const subscribe = useCallback((cb) => (scene ? scene.subscribe(cb) : () => { }), [scene]);
+    const get = useCallback(() => {
+        if (!scene)
+            return undefined;
+        const s = scene.status;
+        if (!shallowEqual(last.current, s))
+            last.current = s;
+        return last.current;
+    }, [scene]);
+    return useSyncExternalStore(subscribe, get, get);
+}

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@synapse-sdk/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Synapse SDK React hooks: connection, topics, calls, services, store.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@synapse-sdk/core": "0.3.0",
+    "@synapse-sdk/client": "0.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/taiga-robotics/synapse"
+  }
+}