@velajs/client 0.1.0 → 0.1.1

package/dist/live-client.js

@@ -1,210 +0,0 @@
-import { COMMIT_CURSOR_HEADER, COMMIT_EPOCH_HEADER } from "@velajs/live-protocol";
-import { RoomConnection } from "./connection.js";
-import { toMutationError } from "./errors.js";
-import { applyOptimisticLayer } from "./optimistic.js";
-import { argsKeyOf, createSubscriptionState, notify, refold, subscriptionKey } from "./subscription.js";
-const DEFAULT_WS_PATH = '/rooms/:room/ws';
-const DEFAULT_ROOM = 'default';
-const DEFAULT_HEARTBEAT_MS = 30_000;
-/**
- * The framework-neutral Vela live client.
- *
- * ```ts
- * const client = new LiveClient<AppLive>({ url: 'https://api.example.com' });
- * const stop = client.subscribe('todos.list', { listId: 'l1' }, (todos) => render(todos));
- * await client.mutate('/todos', { text: 'hi' }, {
- *   optimistic: { query: 'todos.list', args: { listId: 'l1' }, apply: (t = []) => [...t, temp] },
- * });
- * ```
- *
- * Identical `(query, args, room)` subscriptions share one wire registration;
- * reconnects resubscribe with the last cursor+epoch so untouched
- * subscriptions resume without a re-run; optimistic updates are rebaseable
- * layers gated on the mutation's `Vela-Commit-Cursor` response header.
- */ export class LiveClient {
-    options;
-    registry = new Map();
-    connections = new Map();
-    statusListeners = new Set();
-    lastStatus = 'idle';
-    constructor(options){
-        this.options = options;
-    }
-    subscribe(query, args, callback, subscribeOptions) {
-        const room = subscribeOptions?.room ?? this.options.defaultRoom ?? DEFAULT_ROOM;
-        const key = subscriptionKey(query, argsKeyOf(args), room);
-        let state = this.registry.get(key);
-        let fresh = false;
-        if (!state) {
-            state = createSubscriptionState(query, args, room, subscribeOptions?.key);
-            this.registry.set(key, state);
-            fresh = true;
-        }
-        const cb = callback;
-        state.callbacks.add(cb);
-        if (subscribeOptions?.onError) state.errorCallbacks.add(subscribeOptions.onError);
-        // Late joiners get the cached value synchronously (lunora parity).
-        if (state.hasBase || state.layers.length > 0) cb(state.lastValue);
-        if (fresh) this.connectionFor(room).register(state);
-        return ()=>{
-            state.callbacks.delete(cb);
-            if (subscribeOptions?.onError) state.errorCallbacks.delete(subscribeOptions.onError);
-            if (state.callbacks.size === 0) {
-                this.registry.delete(key);
-                this.connectionFor(room).unregister(state);
-            }
-        };
-    }
-    /** The current cached (folded) value — referentially stable between notifications. */ peek(query, args, room) {
-        const state = this.registry.get(subscriptionKey(query, argsKeyOf(args), room ?? this.options.defaultRoom ?? DEFAULT_ROOM));
-        return state?.lastValue;
-    }
-    /**
-   * Fire an HTTP mutation. Optimistic targets paint immediately; the layer
-   * drops when a subscription frame's cursor passes the response's
-   * `Vela-Commit-Cursor` (missing header ⇒ one-shot optimism); a rejection
-   * rolls back. Resolves with the parsed JSON body (undefined when empty).
-   */ async mutate(path, body, mutateOptions) {
-        const handles = [];
-        const paint = (state, transform)=>{
-            const handle = applyOptimisticLayer(state, transform);
-            handles.push({
-                state,
-                handle
-            });
-            if (refold(state)) notify(state);
-        };
-        if (mutateOptions?.optimistic) {
-            const target = mutateOptions.optimistic;
-            const state = this.registry.get(subscriptionKey(target.query, argsKeyOf(target.args), target.room ?? mutateOptions.room ?? this.options.defaultRoom ?? DEFAULT_ROOM));
-            // No live subscription for the target ⇒ nothing displays it: no-op.
-            if (state) paint(state, target.apply);
-        }
-        if (mutateOptions?.optimisticUpdate) {
-            mutateOptions.optimisticUpdate(this.makeStore(mutateOptions, paint));
-        }
-        try {
-            const doFetch = this.options.fetch ?? fetch;
-            const token = await this.options.authToken?.();
-            const headers = {
-                ...body === undefined ? {} : {
-                    'content-type': 'application/json'
-                },
-                ...token === undefined ? {} : {
-                    authorization: `Bearer ${token}`
-                },
-                ...mutateOptions?.headers
-            };
-            const response = await doFetch(new URL(path, this.options.url).toString(), {
-                method: mutateOptions?.method ?? 'POST',
-                headers,
-                ...body === undefined ? {} : {
-                    body: JSON.stringify(body)
-                }
-            });
-            if (!response.ok) throw await toMutationError(response);
-            const stamp = readCommitStamp(response);
-            for (const { state, handle } of handles){
-                // confirm() reports true when the covering frame already arrived —
-                // drop is immediate, re-fold now.
-                if (handle.confirm(stamp) && refold(state)) notify(state);
-            }
-            if (response.status === 204 || response.status === 205) return undefined;
-            try {
-                return await response.json();
-            } catch  {
-                return undefined;
-            }
-        } catch (error) {
-            for (const { state, handle } of handles){
-                if (handle.rollback() && refold(state)) notify(state);
-            }
-            throw error;
-        }
-    }
-    /** Presence heartbeat for a room (see `@velajs/client/presence` for the managed preset). */ presenceBeat(room, meta) {
-        this.connectionFor(room).sendPresence(room, meta);
-    }
-    /** Seed subscription state before connecting (SSR hydration). Subscribes then resume from the seeded cursor. */ hydrate(entries) {
-        for (const entry of entries){
-            const room = entry.room ?? this.options.defaultRoom ?? DEFAULT_ROOM;
-            const key = subscriptionKey(entry.query, argsKeyOf(entry.args), room);
-            if (this.registry.has(key)) continue;
-            const state = createSubscriptionState(entry.query, entry.args, room);
-            state.serverBase = entry.value;
-            state.hasBase = true;
-            state.lastValue = entry.value;
-            state.serverCursor = entry.cursor;
-            state.serverEpoch = entry.epoch;
-            this.registry.set(key, state);
-        }
-    }
-    connectionStatus() {
-        const statuses = [
-            ...this.connections.values()
-        ].map((connection)=>connection.status);
-        if (statuses.includes('connected')) return 'connected';
-        if (statuses.includes('connecting')) return 'connecting';
-        if (statuses.includes('offline')) return 'offline';
-        if (statuses.length > 0 && statuses.every((status)=>status === 'closed')) return 'closed';
-        return 'idle';
-    }
-    onConnectionStatus(listener) {
-        this.statusListeners.add(listener);
-        return ()=>this.statusListeners.delete(listener);
-    }
-    close() {
-        for (const connection of this.connections.values())connection.close();
-    }
-    makeStore(mutateOptions, paint) {
-        const resolve = (query, args, room)=>this.registry.get(subscriptionKey(query, argsKeyOf(args), room ?? mutateOptions.room ?? this.options.defaultRoom ?? DEFAULT_ROOM));
-        return {
-            get: (query, args, room)=>resolve(query, args, room)?.lastValue,
-            set: (query, args, next, room)=>{
-                const state = resolve(query, args, room);
-                if (!state) return;
-                const transform = typeof next === 'function' ? next : ()=>next;
-                paint(state, transform);
-            }
-        };
-    }
-    connectionFor(room) {
-        const wsBase = (this.options.wsUrl ?? this.options.url).replace(/^http/, 'ws');
-        const template = this.options.wsPath ?? DEFAULT_WS_PATH;
-        const path = template.includes(':room') ? template.replace(':room', encodeURIComponent(room)) : template;
-        const url = new URL(path, wsBase).toString();
-        let connection = this.connections.get(url);
-        if (!connection) {
-            connection = new RoomConnection(url, {
-                makeSocket: this.options.WebSocket ?? ((socketUrl)=>{
-                    const WS = globalThis.WebSocket;
-                    if (!WS) {
-                        throw new Error('No WebSocket implementation available — pass one via LiveClientOptions.WebSocket');
-                    }
-                    return new WS(socketUrl);
-                }),
-                authToken: this.options.authToken,
-                heartbeatIntervalMs: this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_MS,
-                reconnect: this.options.reconnect,
-                onStatusChange: ()=>{
-                    const status = this.connectionStatus();
-                    if (status === this.lastStatus) return;
-                    this.lastStatus = status;
-                    for (const listener of this.statusListeners)listener(status);
-                }
-            });
-            this.connections.set(url, connection);
-        }
-        return connection;
-    }
-}
-function readCommitStamp(response) {
-    const cursor = response.headers.get(COMMIT_CURSOR_HEADER);
-    const epoch = response.headers.get(COMMIT_EPOCH_HEADER);
-    if (cursor === null || epoch === null) return undefined;
-    const parsed = Number(cursor);
-    return Number.isFinite(parsed) ? {
-        cursor: parsed,
-        epoch
-    } : undefined;
-}

package/dist/optimistic.d.ts

@@ -1,54 +0,0 @@
-/**
- * Rebaseable, cursor-gated optimistic layers (lunora `optimistic-layers.ts`
- * port). The displayed value is ALWAYS the authoritative server base folded
- * through the pending layers, so:
- *
- * - an unrelated server frame re-folds the layers onto the new base instead of
- *   clobbering the optimistic state ("rebasing");
- * - a layer drops only when a subscription frame arrives whose cursor passes
- *   the mutation's commit cursor (same epoch) — NEVER on HTTP-response
- *   timing, which races the broadcast;
- * - confirm without a stamp (a non-live-aware endpoint) degrades to one-shot
- *   optimism: the layer drops silently and the next authoritative frame
- *   reconciles;
- * - rollback removes the layer and re-folds so the failed write's effect
- *   disappears immediately.
- */
-export interface CommitStamp {
-    cursor: number;
-    epoch: string;
-}
-export interface OptimisticLayer {
-    readonly id: symbol;
-    readonly transform: (current: unknown) => unknown;
-    /** Set by confirm(); the layer is dropped by the first frame whose cursor passes it. */
-    commitCursor?: number;
-    commitEpoch?: string;
-}
-/** The slice of subscription state the optimistic engine operates on. */
-export interface OptimisticHost {
-    layers: OptimisticLayer[];
-    serverBase: unknown;
-    hasBase: boolean;
-    serverCursor?: number;
-    serverEpoch?: string;
-}
-export declare const foldOptimistic: (host: OptimisticHost) => unknown;
-export interface LayerHandle {
-    /**
-     * Record the mutation's commit stamp. With a stamp, the layer survives
-     * until a frame's cursor passes it (dropping immediately when the current
-     * frame already has). Without one, the layer is removed silently — no
-     * re-fold, the incoming authoritative frame reconciles.
-     */
-    confirm(stamp?: CommitStamp): boolean;
-    /** Remove the layer and report whether the host must re-fold + notify. */
-    rollback(): boolean;
-}
-export declare function applyOptimisticLayer(host: OptimisticHost, transform: (current: unknown) => unknown): LayerHandle;
-/**
- * Drop every confirmed layer the frame at (cursor, epoch) covers. A layer
- * confirmed under a DIFFERENT epoch is also dropped — its gate can never fire
- * on this timeline. Returns whether any layer was removed (host re-folds).
- */
-export declare function dropConfirmedLayers(host: OptimisticHost, cursor?: number, epoch?: string): boolean;

package/dist/optimistic.js

@@ -1,67 +0,0 @@
-/**
- * Rebaseable, cursor-gated optimistic layers (lunora `optimistic-layers.ts`
- * port). The displayed value is ALWAYS the authoritative server base folded
- * through the pending layers, so:
- *
- * - an unrelated server frame re-folds the layers onto the new base instead of
- *   clobbering the optimistic state ("rebasing");
- * - a layer drops only when a subscription frame arrives whose cursor passes
- *   the mutation's commit cursor (same epoch) — NEVER on HTTP-response
- *   timing, which races the broadcast;
- * - confirm without a stamp (a non-live-aware endpoint) degrades to one-shot
- *   optimism: the layer drops silently and the next authoritative frame
- *   reconciles;
- * - rollback removes the layer and re-folds so the failed write's effect
- *   disappears immediately.
- */ export const foldOptimistic = (host)=>host.layers.reduce((value, layer)=>layer.transform(value), host.hasBase ? host.serverBase : undefined);
-export function applyOptimisticLayer(host, transform) {
-    const layer = {
-        id: Symbol('optimistic'),
-        transform
-    };
-    host.layers.push(layer);
-    const remove = ()=>{
-        const index = host.layers.indexOf(layer);
-        if (index === -1) return false;
-        host.layers.splice(index, 1);
-        return true;
-    };
-    return {
-        confirm (stamp) {
-            if (!stamp) {
-                remove();
-                return false;
-            }
-            // A stamp from a foreign epoch can never be gated — treat as unstamped.
-            if (host.serverEpoch !== undefined && stamp.epoch !== host.serverEpoch) {
-                remove();
-                return false;
-            }
-            layer.commitCursor = stamp.cursor;
-            layer.commitEpoch = stamp.epoch;
-            // The confirming frame may already have passed while the HTTP response
-            // was in flight — drop now and tell the caller to re-fold.
-            if (host.serverCursor !== undefined && host.serverCursor >= stamp.cursor) {
-                return remove();
-            }
-            return false;
-        },
-        rollback () {
-            return remove();
-        }
-    };
-}
-/**
- * Drop every confirmed layer the frame at (cursor, epoch) covers. A layer
- * confirmed under a DIFFERENT epoch is also dropped — its gate can never fire
- * on this timeline. Returns whether any layer was removed (host re-folds).
- */ export function dropConfirmedLayers(host, cursor, epoch) {
-    if (cursor === undefined) return false;
-    const before = host.layers.length;
-    host.layers = host.layers.filter((layer)=>{
-        if (layer.commitCursor === undefined) return true; // still pending
-        if (epoch !== undefined && layer.commitEpoch !== epoch) return false;
-        return cursor < layer.commitCursor;
-    });
-    return host.layers.length !== before;
-}

package/dist/reconnect.d.ts

@@ -1,13 +0,0 @@
-/**
- * Decorrelated exponential jitter (lunora `reconnect.ts` port): each retry
- * waits a random duration between the base and 3× the previous wait, capped.
- * Decorrelation avoids the reconnect stampede a fixed exponential schedule
- * produces when a fleet of clients drops at once.
- */
-export interface ReconnectState {
-    previousMs?: number;
-}
-export declare const DEFAULT_RECONNECT_BASE_MS = 250;
-export declare const DEFAULT_RECONNECT_CAP_MS = 30000;
-export declare function nextReconnectDelay(state: ReconnectState, baseMs?: number, capMs?: number, random?: () => number): number;
-export declare function resetReconnect(state: ReconnectState): void;

package/dist/reconnect.js

@@ -1,16 +0,0 @@
-/**
- * Decorrelated exponential jitter (lunora `reconnect.ts` port): each retry
- * waits a random duration between the base and 3× the previous wait, capped.
- * Decorrelation avoids the reconnect stampede a fixed exponential schedule
- * produces when a fleet of clients drops at once.
- */ export const DEFAULT_RECONNECT_BASE_MS = 250;
-export const DEFAULT_RECONNECT_CAP_MS = 30_000;
-export function nextReconnectDelay(state, baseMs = DEFAULT_RECONNECT_BASE_MS, capMs = DEFAULT_RECONNECT_CAP_MS, random = Math.random) {
-    const high = Math.max(baseMs, (state.previousMs ?? baseMs) * 3);
-    const delay = Math.min(capMs, baseMs + random() * (high - baseMs));
-    state.previousMs = delay;
-    return delay;
-}
-export function resetReconnect(state) {
-    state.previousMs = undefined;
-}

package/dist/stable-key.d.ts

@@ -1,7 +0,0 @@
-/**
- * Deterministic JSON encoding for cache/dedup keys: object keys are sorted at
- * every depth so `{a,b}` and `{b,a}` produce the same key (lunora
- * `shared/stable-key.ts` pattern). NOT a wire format — wire frames use plain
- * `JSON.stringify` via @velajs/live-protocol's canonical encoders.
- */
-export declare function stableStringify(value: unknown): string;

package/dist/stable-key.js

@@ -1,20 +0,0 @@
-/**
- * Deterministic JSON encoding for cache/dedup keys: object keys are sorted at
- * every depth so `{a,b}` and `{b,a}` produce the same key (lunora
- * `shared/stable-key.ts` pattern). NOT a wire format — wire frames use plain
- * `JSON.stringify` via @velajs/live-protocol's canonical encoders.
- */ export function stableStringify(value) {
-    return JSON.stringify(sortDeep(value));
-}
-function sortDeep(value) {
-    if (Array.isArray(value)) return value.map(sortDeep);
-    if (typeof value === 'object' && value !== null) {
-        const source = value;
-        const out = {};
-        for (const key of Object.keys(source).sort()){
-            out[key] = sortDeep(source[key]);
-        }
-        return out;
-    }
-    return value;
-}

package/dist/subscription.d.ts

@@ -1,42 +0,0 @@
-import type { OptimisticLayer } from './optimistic';
-/**
- * One deduped live subscription: every `subscribe()` for the same
- * (query, args, room) joins a single state (one wire registration, N
- * callbacks), lunora `subscription.ts` style.
- */
-export interface SubscriptionState {
-    /** Wire subscription id — client-chosen, unique per client (thus per socket). */
-    sub: string;
-    query: string;
-    args: unknown;
-    argsKey: string;
-    room: string;
-    key?: string;
-    /** Server acknowledged the registration. */
-    acked: boolean;
-    callbacks: Set<(value: unknown) => void>;
-    errorCallbacks: Set<(error: {
-        code: string;
-        message: string;
-        fatal: boolean;
-    }) => void>;
-    layers: OptimisticLayer[];
-    /** Authoritative value with NO optimistic overlay. */
-    serverBase: unknown;
-    /** Distinguishes "no value yet" from an authoritative `undefined`-shaped value. */
-    hasBase: boolean;
-    serverCursor?: number;
-    serverEpoch?: string;
-    /**
-     * Displayed value = serverBase folded through layers. Reassigned only when
-     * something actually changed, so snapshot consumers (React's
-     * useSyncExternalStore) get referentially stable reads between notifies.
-     */
-    lastValue: unknown;
-}
-export declare const subscriptionKey: (query: string, argsKey: string, room: string) => string;
-export declare const argsKeyOf: (args: unknown) => string;
-export declare function createSubscriptionState(query: string, args: unknown, room: string, key?: string): SubscriptionState;
-/** Re-fold the displayed value; true when it changed (notify). */
-export declare function refold(state: SubscriptionState): boolean;
-export declare function notify(state: SubscriptionState): void;

package/dist/types.d.ts

@@ -1,126 +0,0 @@
-import type { CommitStamp } from './optimistic';
-/**
- * The app-supplied typing contract: one entry per live query, keyed by the
- * server's `@LiveQuery(name)`. Hand-written in v1; shaped so a future
- * `vela codegen` emission (from OpenAPI operationIds + live metadata) is a
- * drop-in replacement.
- *
- * ```ts
- * interface AppLive {
- *   'todos.list': { args: { listId: string }; result: Todo[] };
- * }
- * const client = new LiveClient<AppLive>({ url });
- * ```
- */
-export interface LiveContract {
-    [query: string]: {
-        args: unknown;
-        result: unknown;
-    };
-}
-export type ArgsOf<C, Q extends keyof C> = C[Q] extends {
-    args: infer A;
-} ? A : never;
-export type ResultOf<C, Q extends keyof C> = C[Q] extends {
-    result: infer R;
-} ? R : never;
-export type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'offline' | 'closed';
-/** The WebSocket surface the client uses — injectable for SSR/tests/non-browser runtimes. */
-export interface WebSocketLike {
-    onopen: ((event?: unknown) => void) | null;
-    onmessage: ((event: {
-        data: unknown;
-    }) => void) | null;
-    onclose: ((event?: unknown) => void) | null;
-    onerror: ((event?: unknown) => void) | null;
-    send(data: string): void;
-    close(code?: number, reason?: string): void;
-    readyState: number;
-}
-export type WebSocketFactory = (url: string) => WebSocketLike;
-export interface ReconnectOptions {
-    /** First-retry floor (default 250 ms). */
-    baseMs?: number;
-    /** Backoff ceiling (default 30 000 ms). */
-    capMs?: number;
-}
-export interface LiveClientOptions {
-    /** HTTP(S) base of the Vela app, e.g. `https://api.example.com`. */
-    url: string;
-    /** WS(S) base override; derived from `url` (http→ws) when omitted. */
-    wsUrl?: string;
-    /**
-     * Gateway path template the live socket connects to. A `:room` placeholder
-     * is substituted per subscription room (matching vela's node transport,
-     * which auto-joins the `:id` route param, and Cloudflare's one-DO≈one-room
-     * model). Default `/rooms/:room/ws`.
-     */
-    wsPath?: string;
-    /** Room used when a subscribe/mutate call names none. Default `'default'`. */
-    defaultRoom?: string;
-    /** Injectables — the core never touches globals directly (SSR/edge safety). */
-    WebSocket?: WebSocketFactory;
-    fetch?: typeof fetch;
-    /**
-     * Async token provider, re-invoked per socket connect and per mutation.
-     * Sockets carry it as a `?token=` query param (browsers cannot set WS
-     * headers — use short-lived rotating tokens); mutations as a Bearer header.
-     */
-    authToken?: () => string | undefined | Promise<string | undefined>;
-    /** App-level `{event:'ping'}` keepalive cadence (default 30 000 ms; CF answers without waking the DO). */
-    heartbeatIntervalMs?: number;
-    reconnect?: ReconnectOptions;
-}
-export interface SubscribeOptions {
-    room?: string;
-    /** Delta key-field override forwarded to the server (default `'id'`). */
-    key?: string;
-    onError?: (error: {
-        code: string;
-        message: string;
-        fatal: boolean;
-    }) => void;
-}
-/** Single-subscription optimistic target for `mutate()`. */
-export interface OptimisticTarget<T = unknown> {
-    query: string;
-    args?: unknown;
-    room?: string;
-    apply: (current: T | undefined) => T;
-}
-/** Multi-subscription optimistic store (the `optimisticUpdate` callback's argument). */
-export interface LiveStore {
-    get(query: string, args?: unknown, room?: string): unknown;
-    set(query: string, args: unknown, next: unknown | ((current: unknown) => unknown), room?: string): void;
-}
-export interface MutateOptions {
-    method?: string;
-    headers?: Record<string, string>;
-    room?: string;
-    optimistic?: OptimisticTarget;
-    optimisticUpdate?: (store: LiveStore) => void;
-}
-export type Unsubscribe = () => void;
-/** Seed states before the socket connects (SSR hydration). */
-export interface HydrationEntry {
-    query: string;
-    args?: unknown;
-    room?: string;
-    value: unknown;
-    cursor?: number;
-    epoch?: string;
-}
-/** Durable offline write outbox seam — not implemented in v1 (mutations are plain HTTP). */
-export interface OutboxSink {
-    enqueue(path: string, body: unknown, options?: MutateOptions): Promise<void>;
-    onCommit?(stamp: CommitStamp): void;
-}
-/** Durable read-cache seam (IndexedDB, …) — in-memory only in v1. */
-export interface ReadCacheAdapter {
-    load(key: string): Promise<{
-        value: unknown;
-        cursor?: number;
-        epoch?: string;
-    } | undefined>;
-    persist(key: string, value: unknown, cursor?: number, epoch?: string): Promise<void>;
-}

package/dist/types.js

@@ -1 +0,0 @@
-/** Durable read-cache seam (IndexedDB, …) — in-memory only in v1. */ export { };