@synapse-sdk/client 0.1.0 → 0.3.0

package/dist/signals.d.ts

@@ -0,0 +1,10 @@
+interface Closable {
+    close(): Promise<void>;
+}
+/** True in Bun/Node (a `process` with `versions.node`), false in browsers and workers. */
+export declare function isServerRuntime(): boolean;
+/** Adds a node to the set closed on SIGINT/SIGTERM; installs the handler on first use. No-op outside Bun/Node. */
+export declare function closeOnSignals(node: Closable): void;
+/** Removes a node (it closed on its own); the handler goes with the last node so a finished process keeps the default disposition. */
+export declare function forgetOnSignals(node: Closable): void;
+export {};

package/dist/signals.js

@@ -0,0 +1,63 @@
+// Clean close on SIGINT/SIGTERM in Bun/Node (SDK §2, D 2026-09-27): a killed client must tell the
+// broker it is leaving, so its cid and index entries are released at once instead of lingering
+// until the relay's idle timeout reaps the session. Browsers have no signals; nothing installs there.
+//
+// One process-wide handler serves every open node: on the first signal it closes all of them
+// (bounded by CLOSE_GRACE_MS), removes itself, and re-raises the same signal so the process ends
+// with the default disposition and exit status (130 for SIGINT, 143 for SIGTERM) — the SDK never
+// picks an exit code of its own. Opt out per node with `signals: false`.
+const SIGNALS = ["SIGINT", "SIGTERM"];
+const EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+/** Upper bound on the flush: `close()` waits up to 500 ms for the session's close to settle. */
+const CLOSE_GRACE_MS = 1000;
+const nodes = new Set();
+let installed = false;
+function proc() {
+    const p = globalThis.process;
+    return p && typeof p.versions?.node === "string" && typeof p.on === "function" ? p : undefined;
+}
+/** True in Bun/Node (a `process` with `versions.node`), false in browsers and workers. */
+export function isServerRuntime() { return proc() !== undefined; }
+/** Adds a node to the set closed on SIGINT/SIGTERM; installs the handler on first use. No-op outside Bun/Node. */
+export function closeOnSignals(node) {
+    const p = proc();
+    if (!p)
+        return;
+    nodes.add(node);
+    if (installed)
+        return;
+    installed = true;
+    for (const sig of SIGNALS)
+        p.on(sig, onSignal);
+}
+/** Removes a node (it closed on its own); the handler goes with the last node so a finished process keeps the default disposition. */
+export function forgetOnSignals(node) {
+    nodes.delete(node);
+    if (nodes.size > 0 || !installed)
+        return;
+    installed = false;
+    const p = proc();
+    if (p)
+        for (const sig of SIGNALS)
+            p.off(sig, onSignal);
+}
+function onSignal(sig) {
+    const p = proc();
+    for (const s of SIGNALS)
+        p.off(s, onSignal);
+    installed = false;
+    const live = [...nodes];
+    nodes.clear();
+    const closed = Promise.allSettled(live.map(n => n.close()));
+    const grace = new Promise(r => setTimeout(r, CLOSE_GRACE_MS));
+    void Promise.race([closed, grace]).then(() => {
+        try {
+            p.kill(p.pid, sig);
+        }
+        catch {
+            p.exit(EXIT_CODE[sig]);
+        }
+        // The default disposition ends the process asynchronously; if the runtime ignores the re-raise, fall back.
+        setTimeout(() => p.exit(EXIT_CODE[sig]), 200);
+    });
+}

package/dist/store.d.ts

@@ -0,0 +1,145 @@
+import { SynapseError, type ActiveProject, type Role, type StoreAccess, type StoreDiff, type StoreMode, type StoreOnDeath, type StoreRow, type StoreSnapshot } from "@synapse-sdk/core";
+import type { Node } from "./node.ts";
+import { type Session } from "./session.ts";
+import type { Warn } from "./topics.ts";
+import type { StoreChange, StoreHandle, StoreOptions, StoreStatus } from "./types.ts";
+import { AsyncQueue, type Deferred } from "./util.ts";
+export declare const ENDED_DESTROYED = "destroyed";
+export declare const ENDED_CONNECTION_LOST = "connection_lost";
+export declare const ENDED_CLIENT = "client";
+/** A watcher this many batches behind is ended, never grown. */
+export declare const STORE_FEED_CAP = 256;
+/** The mirror and what the runtime said about the namespace; written by the task and its reader only. */
+export declare class State {
+    #private;
+    epoch: string | undefined;
+    version: number;
+    rows: Map<string, StoreRow>;
+    flat: ReadonlyMap<string, unknown>;
+    mode: StoreMode | undefined;
+    owner: string | undefined;
+    mine: boolean;
+    claim: string | undefined;
+    minRole: Role | undefined;
+    onDeath: StoreOnDeath | undefined;
+    absent: boolean;
+    loaded: boolean;
+    gap: boolean;
+    pending: number;
+    ended: string | undefined;
+    subscribe(l: () => void): () => void;
+    watch(): AsyncQueue<StoreChange[]>;
+    /** A feed its reader has left: it is closed and gets nothing more. */
+    unwatch(q: AsyncQueue<StoreChange[]>): void;
+    applySnapshot(s: StoreSnapshot): void;
+    applyDiff(d: StoreDiff, warn: Warn): void;
+    /** Nothing of the incarnation is known until the runtime answers the next open. */
+    reset(): void;
+    opened(a: StoreAccess | undefined): void;
+    end(reason: string): void;
+    setPending(n: number): void;
+    /** The status a handle reports: a closed handle (`closed`) has ended (`client`) whatever the namespace does. */
+    status(nodeConnected: boolean, closed?: boolean): StoreStatus;
+}
+type Result<T> = {
+    ok: T;
+} | {
+    err: SynapseError;
+};
+interface WriteOp {
+    key?: string;
+    value?: unknown;
+    values?: Record<string, unknown>;
+}
+type Event = {
+    kind: "session";
+    session: Session;
+} | {
+    kind: "sessionEnded";
+} | {
+    kind: "nodeEnded";
+} | {
+    kind: "opened";
+    attempt: number;
+    result: Result<unknown>;
+} | {
+    kind: "applied";
+    epoch: string;
+    version: number;
+} | {
+    kind: "followEnded";
+    attempt: number;
+    reason: string | undefined;
+} | {
+    kind: "join";
+    reply: Deferred<void>;
+} | {
+    kind: "waitVersion";
+    epoch: string;
+    version: number;
+    reply: Deferred<void>;
+} | {
+    kind: "write";
+    op: string;
+    args: WriteOp;
+    reply: Deferred<unknown>;
+} | {
+    kind: "writeDone";
+    op: string;
+    result: Result<unknown>;
+    reply: Deferred<unknown>;
+} | {
+    kind: "projectChanged";
+    now: ActiveProject | null;
+} | {
+    kind: "paced";
+    attempt: number;
+} | {
+    kind: "close";
+};
+/** The namespace shared by its handles and its task. */
+export declare class Namespace {
+    readonly name: string;
+    readonly opts: StoreOptions;
+    readonly node: Node;
+    readonly warn: Warn;
+    readonly state: State;
+    readonly mailbox: AsyncQueue<Event>;
+    readonly exited: Deferred<void>;
+    handles: number;
+    constructor(name: string, opts: StoreOptions, node: Node, warn: Warn);
+    post(e: Event): boolean;
+    request<T>(make: (reply: Deferred<T>) => Event): Promise<T>;
+}
+export declare function startNamespace(ns: Namespace, registry: Map<string, Namespace>): void;
+/** The application's handle on a namespace: the last one closed ends the task. */
+export declare class StoreHandleImpl implements StoreHandle {
+    #private;
+    private readonly ns;
+    constructor(ns: Namespace);
+    get name(): string;
+    /** The whole value, what the runtime has; the same object while nothing changed (reference-stable for React). */
+    get value(): Record<string, unknown>;
+    get(key: string): unknown;
+    get synced(): boolean;
+    get status(): StoreStatus;
+    /** `set(key, value)` or `set({ ...several keys })` (one atomic write); resolves once `value` shows it. */
+    set(keyOrValues: string | Record<string, unknown>, value?: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    destroy(): Promise<void>;
+    /** `for await (const value of store.watch())`: the whole value after each change; `store.watch(key)`: that key's value each time it changes. Ends with the handle; leaving the loop removes the feed. */
+    watch(key?: string): AsyncGenerator<unknown, void, undefined>;
+    /** The framework bridge (React's `useStore`): called on every change of the value or the status. */
+    subscribe(listener: () => void): () => void;
+    /** Waits for the namespace to be in (the first snapshot applied, or absent). */
+    join(): Promise<void>;
+    close(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * `store(name, opts)`: one task per namespace per node; a second `store` with the same options joins
+ * it (no open written), with other options `invalid_input`; one exiting is waited out.
+ */
+export declare function openStore(node: Node, registry: Map<string, Namespace>, name: string, opts: StoreOptions, warn: Warn): Promise<StoreHandleImpl>;
+export {};