@carno.js/live 1.8.0

package/dist/client/core.d.ts

@@ -0,0 +1,111 @@
+import type { LiveInputs } from '../shared/inputs';
+import { type ClientTransport } from './transport';
+export interface LiveState<T> {
+    data: T | undefined;
+    pending: boolean;
+    error: string | null;
+    /** The server cannot vouch for this being current. Data still shown. */
+    stale: boolean;
+}
+export interface LiveStore<T> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): LiveState<T>;
+}
+/** The slice of WebSocket this client uses, and the seam tests inject through. */
+export interface LiveSocket {
+    send(data: string): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    onclose: (() => void) | null;
+    onerror: ((error: unknown) => void) | null;
+}
+export interface LiveClientOptions {
+    url: string;
+    token?: string;
+    /**
+     * Server-rendered payloads, keyed by `${resource}|${canonical(inputs)}`.
+     * Lets the first paint skip the waterfall: the store starts full and the
+     * subscription only says "this is the hash I already have".
+     */
+    hydrate?: Record<string, {
+        data: unknown;
+        hash: string;
+    }>;
+    unsubGraceMs?: number;
+    reconnect?: {
+        initialMs?: number;
+        maxMs?: number;
+    };
+    socketFactory?: (url: string) => LiveSocket;
+    /**
+     * Builds the pipe. Defaults to the WebSocket → SSE → polling ladder.
+     * `socketFactory` still works and is the shorthand for "same ladder,
+     * different socket" that the tests use.
+     */
+    transportFactory?: (url: string) => ClientTransport;
+    /**
+     * The `routes` object the @carno.js/client codegen emits. Only the polling
+     * rung needs it -- without it the ladder stops at SSE, and says so.
+     */
+    routes?: unknown;
+    pollIntervalMs?: number;
+    transportProbeMs?: number;
+    /** Origin the SSE and polling rungs call. Defaults to the page's own. */
+    httpBaseUrl?: string;
+    /** SSE downstream path. Must match the server's `config.ssePath`. */
+    ssePath?: string;
+    /** SSE control path. Must match the server's `config.sseControlPath`. */
+    sseControlPath?: string;
+}
+export declare class LiveClient {
+    private readonly options;
+    private readonly entries;
+    private readonly bySid;
+    private readonly overlays;
+    private nextOverlay;
+    private pipe;
+    private connected;
+    private closed;
+    private attempt;
+    private reconnectTimer;
+    private nextSid;
+    constructor(options: LiveClientOptions);
+    store<T>(resource: string, inputs: LiveInputs): LiveStore<T>;
+    /**
+     * Show something the server has not confirmed yet.
+     *
+     * The overlay is a projection over the confirmed snapshot, never a write
+     * into it: a patch arriving while the action is in flight lands on the
+     * snapshot and the overlay is re-projected on top, so the screen never
+     * flickers back to a state the server does not know about.
+     *
+     * `apply` receives a mutable draft: mutate it, do not return a new value.
+     * Returns the function that removes the overlay.
+     */
+    overlay(resourceId: string, apply: (draft: any) => void): () => void;
+    close(): void;
+    /** Which pipe is carrying this client right now. For logs, not for logic. */
+    transport(): ClientTransport['kind'] | null;
+    private retain;
+    private ensureConnected;
+    /**
+     * WebSocket, then SSE, then polling. Rungs whose prerequisites are missing
+     * are not offered: a polling rung with no route index would fail every
+     * subscription with the same error.
+     */
+    private buildLadder;
+    private onDisconnect;
+    private sendSub;
+    private send;
+    private onMessage;
+    /** A server error ends this subscription; keep its store state, not its binding. */
+    private terminate;
+    /** Confirmed snapshot plus every overlay registered for this resource. */
+    private project;
+    private reproject;
+    private update;
+}
+export declare function storeKey(resource: string, inputs: LiveInputs): string;

package/dist/client/core.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveClient = void 0;
+exports.storeKey = storeKey;
+const PatchEngine_1 = require("../patch/PatchEngine");
+const canonical_1 = require("../shared/canonical");
+const protocol_1 = require("../shared/protocol");
+const transport_1 = require("./transport");
+const DEFAULT_UNSUB_GRACE_MS = 5000;
+const DEFAULT_INITIAL_BACKOFF_MS = 250;
+const DEFAULT_MAX_BACKOFF_MS = 30000;
+class LiveClient {
+    constructor(options) {
+        this.options = options;
+        this.entries = new Map();
+        this.bySid = new Map();
+        this.overlays = new Map();
+        this.nextOverlay = 0;
+        this.pipe = null;
+        this.connected = false;
+        this.closed = false;
+        this.attempt = 0;
+        this.reconnectTimer = null;
+        this.nextSid = 0;
+    }
+    store(resource, inputs) {
+        const key = storeKey(resource, inputs);
+        const existing = this.entries.get(key);
+        if (existing) {
+            return existing.store;
+        }
+        const hydrated = this.options.hydrate?.[key];
+        const entry = {
+            sid: `s${this.nextSid++}`,
+            key,
+            resource,
+            inputs,
+            refs: 0,
+            revision: hydrated ? 1 : 0,
+            hash: hydrated?.hash ?? null,
+            patcher: new PatchEngine_1.PatchEngine(),
+            confirmed: hydrated?.data,
+            state: {
+                data: hydrated?.data,
+                pending: hydrated === undefined,
+                error: null,
+                stale: false
+            },
+            listeners: new Set(),
+            dropTimer: null,
+            terminal: false,
+            store: undefined
+        };
+        entry.store = {
+            subscribe: (listener) => this.retain(entry, listener),
+            getSnapshot: () => entry.state
+        };
+        this.entries.set(key, entry);
+        this.bySid.set(entry.sid, entry);
+        return entry.store;
+    }
+    /**
+     * Show something the server has not confirmed yet.
+     *
+     * The overlay is a projection over the confirmed snapshot, never a write
+     * into it: a patch arriving while the action is in flight lands on the
+     * snapshot and the overlay is re-projected on top, so the screen never
+     * flickers back to a state the server does not know about.
+     *
+     * `apply` receives a mutable draft: mutate it, do not return a new value.
+     * Returns the function that removes the overlay.
+     */
+    overlay(resourceId, apply) {
+        const id = this.nextOverlay++;
+        this.overlays.set(id, { resource: resourceId, apply: apply });
+        this.reproject(resourceId);
+        return () => {
+            if (this.overlays.delete(id)) {
+                this.reproject(resourceId);
+            }
+        };
+    }
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.pipe?.close();
+        this.pipe = null;
+        this.connected = false;
+    }
+    /** Which pipe is carrying this client right now. For logs, not for logic. */
+    transport() {
+        return this.connected ? (this.pipe?.kind ?? null) : null;
+    }
+    // ------------------------------------------------------------ lifecycle
+    retain(entry, listener) {
+        entry.listeners.add(listener);
+        entry.refs += 1;
+        if (entry.dropTimer) {
+            clearTimeout(entry.dropTimer);
+            entry.dropTimer = null;
+        }
+        if (entry.refs === 1) {
+            const openedSynchronously = this.ensureConnected();
+            if (!openedSynchronously) {
+                this.sendSub(entry);
+            }
+        }
+        return () => {
+            entry.listeners.delete(listener);
+            entry.refs -= 1;
+            if (entry.terminal || entry.refs > 0 || entry.dropTimer) {
+                return;
+            }
+            // Grace period: coming back from a navigation must not tear the
+            // subscription down and build it again.
+            entry.dropTimer = setTimeout(() => {
+                entry.dropTimer = null;
+                if (entry.refs > 0) {
+                    return;
+                }
+                this.send({ t: 'unsub', sid: entry.sid });
+                this.entries.delete(entry.key);
+                this.bySid.delete(entry.sid);
+            }, this.options.unsubGraceMs ?? DEFAULT_UNSUB_GRACE_MS);
+        };
+    }
+    ensureConnected() {
+        if (this.pipe || this.closed) {
+            return false;
+        }
+        const build = this.options.transportFactory ?? ((url) => this.buildLadder(url));
+        const pipe = build(this.options.url);
+        this.pipe = pipe;
+        let openedSynchronously = false;
+        pipe.start({
+            onOpen: () => {
+                openedSynchronously = true;
+                this.connected = true;
+                this.attempt = 0;
+                this.send({ t: 'hello', v: protocol_1.LIVE_PROTOCOL_VERSION, token: this.options.token });
+                // Reconnect is just "subscribe again, carrying the hash of
+                // what is on screen". There is no session to restore, because
+                // there is no session.
+                for (const entry of this.entries.values()) {
+                    if (entry.refs > 0) {
+                        this.sendSub(entry);
+                    }
+                }
+            },
+            onMessage: raw => this.onMessage(raw),
+            onClose: () => this.onDisconnect()
+        });
+        return openedSynchronously;
+    }
+    /**
+     * WebSocket, then SSE, then polling. Rungs whose prerequisites are missing
+     * are not offered: a polling rung with no route index would fail every
+     * subscription with the same error.
+     */
+    buildLadder(url) {
+        const origin = this.options.httpBaseUrl
+            ?? url.replace(/^ws/, 'http').replace(/\/live\/?$/, '');
+        const index = (0, transport_1.routeIndex)(this.options.routes);
+        const rungs = [
+            () => new transport_1.WebSocketTransport(url, this.options.socketFactory),
+            () => new transport_1.SseClientTransport(origin, {
+                streamPath: this.options.ssePath,
+                controlPath: this.options.sseControlPath
+            })
+        ];
+        if (Object.keys(index).length > 0) {
+            rungs.push(() => new transport_1.PollingTransport(origin, index, {
+                intervalMs: this.options.pollIntervalMs,
+                token: this.options.token
+            }));
+        }
+        return new transport_1.LadderTransport(rungs, { probeMs: this.options.transportProbeMs ?? 3000 });
+    }
+    onDisconnect() {
+        this.connected = false;
+        this.pipe = null;
+        if (this.closed || this.reconnectTimer) {
+            return;
+        }
+        const initial = this.options.reconnect?.initialMs ?? DEFAULT_INITIAL_BACKOFF_MS;
+        const max = this.options.reconnect?.maxMs ?? DEFAULT_MAX_BACKOFF_MS;
+        const ceiling = Math.min(max, initial * 2 ** this.attempt);
+        // Full jitter, and it is mandatory: a deploy reconnects every client at
+        // once, and a synchronised recompute storm takes the database down.
+        const delay = Math.random() * ceiling;
+        this.attempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.ensureConnected();
+        }, delay);
+    }
+    sendSub(entry) {
+        this.send({
+            t: 'sub',
+            sid: entry.sid,
+            resource: entry.resource,
+            inputs: entry.inputs,
+            hash: entry.hash ?? undefined
+        });
+    }
+    send(message) {
+        if (!this.pipe || !this.connected) {
+            return;
+        }
+        this.pipe.send(JSON.stringify(message));
+    }
+    // -------------------------------------------------------------- inbound
+    onMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const entry = this.bySid.get(message.sid ?? '');
+        if (!entry) {
+            return;
+        }
+        switch (message.t) {
+            case 'snapshot':
+                if (message.key) {
+                    entry.patcher = new PatchEngine_1.PatchEngine(message.key);
+                }
+                entry.revision = message.rev;
+                entry.hash = message.hash;
+                entry.confirmed = message.data;
+                this.project(entry, { pending: false, error: null, stale: false });
+                return;
+            case 'current':
+                if (message.key) {
+                    entry.patcher = new PatchEngine_1.PatchEngine(message.key);
+                }
+                entry.revision = message.rev;
+                entry.hash = message.hash;
+                // Content already on screen: touch only the flags, keep the
+                // data referentially identical so nothing re-renders.
+                this.project(entry, { pending: false, error: null, stale: false });
+                return;
+            case 'patch':
+                if (message.from !== entry.revision) {
+                    // A hole in the sequence. Ask for full state rather than
+                    // applying ops to a base we cannot vouch for.
+                    this.send({ t: 'resync', sid: entry.sid, hash: entry.hash ?? undefined });
+                    return;
+                }
+                entry.revision = message.to;
+                entry.hash = message.hash;
+                entry.confirmed = entry.patcher.apply(entry.confirmed, message.ops);
+                this.project(entry, { pending: false, error: null, stale: false });
+                return;
+            case 'stale':
+                this.update(entry, { ...entry.state, stale: true });
+                return;
+            case 'error':
+                this.terminate(entry);
+                this.update(entry, { ...entry.state, pending: false, error: message.message });
+                return;
+        }
+    }
+    /** A server error ends this subscription; keep its store state, not its binding. */
+    terminate(entry) {
+        entry.terminal = true;
+        if (entry.dropTimer) {
+            clearTimeout(entry.dropTimer);
+            entry.dropTimer = null;
+        }
+        if (this.entries.get(entry.key) === entry) {
+            this.entries.delete(entry.key);
+        }
+        if (this.bySid.get(entry.sid) === entry) {
+            this.bySid.delete(entry.sid);
+        }
+    }
+    /** Confirmed snapshot plus every overlay registered for this resource. */
+    project(entry, flags) {
+        const overlays = [...this.overlays.values()].filter(overlay => overlay.resource === entry.resource);
+        if (overlays.length === 0 || entry.confirmed === undefined) {
+            this.update(entry, { ...flags, data: entry.confirmed });
+            return;
+        }
+        const draft = structuredClone(entry.confirmed);
+        for (const overlay of overlays) {
+            try {
+                overlay.apply(draft);
+            }
+            catch (error) {
+                // A broken optimistic update must not take the real data with
+                // it: the confirmed snapshot is still correct underneath.
+                console.error('[carno:live] an optimistic overlay failed', error);
+            }
+        }
+        this.update(entry, { ...flags, data: draft });
+    }
+    reproject(resourceId) {
+        for (const entry of this.entries.values()) {
+            if (entry.resource !== resourceId) {
+                continue;
+            }
+            this.project(entry, {
+                pending: entry.state.pending,
+                error: entry.state.error,
+                stale: entry.state.stale
+            });
+        }
+    }
+    update(entry, next) {
+        if (next.data === entry.state.data &&
+            next.pending === entry.state.pending &&
+            next.error === entry.state.error &&
+            next.stale === entry.state.stale) {
+            // Nothing changed. Keeping the same object is what makes
+            // useSyncExternalStore stable instead of looping.
+            return;
+        }
+        entry.state = next;
+        for (const listener of entry.listeners) {
+            listener();
+        }
+    }
+}
+exports.LiveClient = LiveClient;
+function storeKey(resource, inputs) {
+    return `${resource}|${(0, canonical_1.canonical)({
+        params: inputs.params ?? {},
+        query: inputs.query ?? {},
+        body: inputs.body ?? null
+    })}`;
+}

package/dist/client/hydrate.d.ts

@@ -0,0 +1,19 @@
+import type { LivePayload } from '../resource/prefetch';
+/** Attribute the island helper marks its payload scripts with. */
+export declare const HYDRATION_ATTRIBUTE = "data-carno-live";
+/** Exactly the key `LiveClient.store()` will look up. */
+export declare function hydrationKey(payload: LivePayload): string;
+export declare function toHydrateMap(payloads: LivePayload[]): Record<string, {
+    data: unknown;
+    hash: string;
+}>;
+/**
+ * Collect every island payload the server embedded in the page.
+ *
+ * A malformed one is skipped rather than thrown: one broken island must not
+ * cost the page every other island's first paint.
+ */
+export declare function readHydrationPayload(root?: ParentNode): Record<string, {
+    data: unknown;
+    hash: string;
+}>;

package/dist/client/hydrate.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HYDRATION_ATTRIBUTE = void 0;
+exports.hydrationKey = hydrationKey;
+exports.toHydrateMap = toHydrateMap;
+exports.readHydrationPayload = readHydrationPayload;
+const core_1 = require("./core");
+/** Attribute the island helper marks its payload scripts with. */
+exports.HYDRATION_ATTRIBUTE = 'data-carno-live';
+/** Exactly the key `LiveClient.store()` will look up. */
+function hydrationKey(payload) {
+    return (0, core_1.storeKey)(payload.resourceId, payload.inputs);
+}
+function toHydrateMap(payloads) {
+    const map = {};
+    for (const payload of payloads) {
+        if (!isLivePayload(payload)) {
+            continue;
+        }
+        map[hydrationKey(payload)] = { data: payload.data, hash: payload.hash };
+    }
+    return map;
+}
+/**
+ * Collect every island payload the server embedded in the page.
+ *
+ * A malformed one is skipped rather than thrown: one broken island must not
+ * cost the page every other island's first paint.
+ */
+function readHydrationPayload(root = document) {
+    const payloads = [];
+    for (const node of root.querySelectorAll(`script[${exports.HYDRATION_ATTRIBUTE}]`)) {
+        try {
+            payloads.push(JSON.parse(node.textContent ?? ''));
+        }
+        catch {
+            // Skip it. The client will fetch that one instead.
+        }
+    }
+    return toHydrateMap(payloads);
+}
+function isLivePayload(value) {
+    if (!isRecord(value) || typeof value.resourceId !== 'string' || value.resourceId.length === 0) {
+        return false;
+    }
+    return typeof value.hash === 'string'
+        && value.hash.length > 0
+        && isLiveInputs(value.inputs);
+}
+function isLiveInputs(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const params = value.params;
+    const query = value.query;
+    if (!isRecord(params) || !isRecord(query)) {
+        return false;
+    }
+    return Object.values(params).every(item => typeof item === 'string')
+        && Object.values(query).every(item => typeof item === 'string'
+            || (Array.isArray(item) && item.every(value => typeof value === 'string')));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/client/optimistic.d.ts

@@ -0,0 +1,17 @@
+import type { LiveDataOf, LiveDescriptor } from '../shared/descriptor';
+/**
+ * One optimistic projection: which resource it targets, and how the action's
+ * payload changes it.
+ *
+ * `on` is what makes `draft` typed. Without naming the target, the draft would
+ * have to be `any`, and an optimistic update on `any` is a guess the compiler
+ * cannot check.
+ */
+export interface OptimisticEntry<Target, Dto> {
+    on: Target;
+    apply: (draft: LiveDataOf<Target extends LiveDescriptor<infer R> ? R : never>, dto: Dto) => void;
+}
+/** Maps a tuple of descriptors to the matching tuple of optimistic entries. */
+export type OptimisticList<Targets extends readonly unknown[], Dto> = {
+    [K in keyof Targets]: OptimisticEntry<Targets[K], Dto>;
+};

package/dist/client/optimistic.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/client/react.d.ts

@@ -0,0 +1,22 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { type LiveDataOf, type LiveDescriptor, type LiveInputsOf } from '../shared/descriptor';
+import type { LiveInputs } from '../shared/inputs';
+import type { LiveClient, LiveState } from './core';
+import type { OptimisticList } from './optimistic';
+export declare const LiveContext: import("react").Context<LiveClient>;
+export declare function LiveProvider(props: {
+    client: LiveClient;
+    children?: ReactNode;
+}): ReactElement;
+export declare function useLive<T>(resource: string, inputs?: Partial<LiveInputs>): LiveState<T>;
+export declare function useLive<R>(descriptor: LiveDescriptor<R>, inputs?: LiveInputsOf<R>): LiveState<LiveDataOf<R>>;
+/**
+ * Run an action, showing its expected effect immediately.
+ *
+ * The overlay lives above the confirmed snapshot, so a server patch arriving
+ * mid-flight lands underneath it and nothing flickers. It is removed when the
+ * action settles, either way.
+ */
+export declare function useLiveAction<Dto, Result, const Targets extends readonly LiveDescriptor<any>[]>(action: (dto: Dto) => Promise<Result>, options?: {
+    optimistic?: OptimisticList<Targets, Dto>;
+}): (dto: Dto) => Promise<Result>;

package/dist/client/react.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveContext = void 0;
+exports.LiveProvider = LiveProvider;
+exports.useLive = useLive;
+exports.useLiveAction = useLiveAction;
+const react_1 = require("react");
+const canonical_1 = require("../shared/canonical");
+const descriptor_1 = require("../shared/descriptor");
+exports.LiveContext = (0, react_1.createContext)(null);
+function LiveProvider(props) {
+    return (0, react_1.createElement)(exports.LiveContext.Provider, { value: props.client }, props.children);
+}
+/**
+ * Subscribe a component to server-owned state.
+ *
+ * The component keeps its own local state next to this — selected row, open
+ * modal, focused input. None of that travels; only the server's data does.
+ */
+function useLive(resource, 
+// Loose on purpose, and invisible to callers: a descriptor's own `query`
+// type is a plain object, which no index signature accepts. The overloads
+// above are what anyone actually sees.
+inputs = {}) {
+    const client = (0, react_1.useContext)(exports.LiveContext);
+    if (!client) {
+        throw new Error('useLive() requires a <LiveProvider client={...}> above it in the tree.');
+    }
+    const resourceId = typeof resource === 'string' ? resource : (0, descriptor_1.resourceIdOf)(resource);
+    const normalized = (0, descriptor_1.normalizeLiveInputs)(inputs);
+    const identity = (0, canonical_1.canonical)({
+        params: normalized.params,
+        query: normalized.query,
+        body: normalized.body ?? null
+    });
+    // Depend on the canonical form, not on the object: a new literal every
+    // render would resubscribe on every render.
+    const stable = (0, react_1.useMemo)(() => normalized, [identity]);
+    const store = (0, react_1.useMemo)(() => client.store(resourceId, stable), [client, resourceId, stable]);
+    return (0, react_1.useSyncExternalStore)(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+/**
+ * Run an action, showing its expected effect immediately.
+ *
+ * The overlay lives above the confirmed snapshot, so a server patch arriving
+ * mid-flight lands underneath it and nothing flickers. It is removed when the
+ * action settles, either way.
+ */
+function useLiveAction(action, options = {}) {
+    const client = (0, react_1.useContext)(exports.LiveContext);
+    if (!client) {
+        throw new Error('useLiveAction() requires a <LiveProvider client={...}> above it in the tree.');
+    }
+    // The array is a fresh literal on every render; a ref keeps the returned
+    // function stable without making the dependency list lie.
+    const specs = (0, react_1.useRef)([]);
+    specs.current = (options.optimistic ?? []);
+    return (0, react_1.useCallback)(async (dto) => {
+        const remove = specs.current.map(spec => client.overlay((0, descriptor_1.resourceIdOf)(spec.on), draft => spec.apply(draft, dto)));
+        try {
+            return await action(dto);
+        }
+        finally {
+            for (const drop of remove) {
+                drop();
+            }
+        }
+    }, [client, action]);
+}