@vantage-ui/client 0.0.0-stage → 0.4.4

package/dist/persist.js

@@ -0,0 +1,108 @@
+// Offline mirror and outbox.
+//
+// Tables marked `persist: true` on the server are mirrored here; on the
+// next start the app paints from the mirror (records marked `stale`)
+// before the socket connects. Edits made while offline wait in memory and
+// go out in order on reconnect, within the same page. They are also saved
+// to the outbox, but nothing sends a saved outbox after a reload: edits
+// still waiting when the page reloads are lost.
+/** Keeps everything in memory (tests; SSR). */
+export class MemoryStorage {
+    records = new Map();
+    cursor = null;
+    outbox = [];
+    async load() {
+        return { records: [...this.records.values()], cursor: this.cursor, outbox: [...this.outbox] };
+    }
+    async save(change) {
+        for (const r of change.records ?? []) {
+            const key = `${r.table}\u0000${r.id}`;
+            if (r.record)
+                this.records.set(key, { table: r.table, record: r.record });
+            else
+                this.records.delete(key);
+        }
+        if (change.cursor)
+            this.cursor = change.cursor;
+        if (change.outbox)
+            this.outbox = [...change.outbox];
+    }
+    async clear() {
+        this.records.clear();
+        this.cursor = null;
+        this.outbox = [];
+    }
+}
+/**
+ * IndexedDB, one database per server + schema. A schema change starts a
+ * fresh database (`name` includes the hash), so stale shapes never load.
+ */
+export class IndexedDBStorage {
+    name;
+    schemaHash;
+    db;
+    constructor(name, schemaHash) {
+        this.name = name;
+        this.schemaHash = schemaHash;
+    }
+    open() {
+        this.db ??= new Promise((resolve, reject) => {
+            const request = indexedDB.open(`vantage:${this.name}:${this.schemaHash}`, 1);
+            request.onupgradeneeded = () => {
+                const db = request.result;
+                db.createObjectStore("records");
+                db.createObjectStore("meta");
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+        return this.db;
+    }
+    async load() {
+        const db = await this.open();
+        const tx = db.transaction(["records", "meta"], "readonly");
+        const [records, cursor, outbox] = await Promise.all([
+            req(tx.objectStore("records").getAll()),
+            req(tx.objectStore("meta").get("cursor")),
+            req(tx.objectStore("meta").get("outbox")),
+        ]);
+        return { records, cursor: cursor ?? null, outbox: outbox ?? [] };
+    }
+    async save(change) {
+        const db = await this.open();
+        const tx = db.transaction(["records", "meta"], "readwrite");
+        const records = tx.objectStore("records");
+        for (const r of change.records ?? []) {
+            const key = `${r.table}\u0000${r.id}`;
+            if (r.record)
+                records.put({ table: r.table, record: r.record }, key);
+            else
+                records.delete(key);
+        }
+        if (change.cursor)
+            tx.objectStore("meta").put(change.cursor, "cursor");
+        if (change.outbox)
+            tx.objectStore("meta").put(change.outbox, "outbox");
+        await done(tx);
+    }
+    async clear() {
+        const db = await this.open();
+        const tx = db.transaction(["records", "meta"], "readwrite");
+        tx.objectStore("records").clear();
+        tx.objectStore("meta").clear();
+        await done(tx);
+    }
+}
+function req(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+function done(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.onabort = () => reject(tx.error);
+    });
+}

package/dist/protocol.d.ts

@@ -0,0 +1,236 @@
+/** The wire protocol this client speaks; sent in `hello`. */
+export declare const PROTOCOL = 1;
+/** What this client understands beyond the protocol; sent in `hello`. */
+export declare const FEATURES: string[];
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type WireRecord = {
+    id: string;
+    $actions?: string[];
+} & Record<string, unknown>;
+export type Op = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in" | "like";
+export type Where = [column: string, op: Op, value: unknown];
+export type Sort = [column: string, direction: "asc" | "desc"];
+export interface CollectionSpec {
+    table: string;
+    where?: Where[];
+    search?: string;
+    sort?: Sort;
+    via?: {
+        table: string;
+        id: string;
+        ref: string;
+    };
+    limit?: number;
+}
+export interface Cursor {
+    epoch: string;
+    seq: number;
+}
+export type ChangeEvent = {
+    k: "upsert";
+    table: string;
+    id: string;
+    record: WireRecord;
+} | {
+    k: "removed";
+    table: string;
+    id: string;
+} | {
+    k: "invalidated";
+    table: string;
+};
+export type ErrorKind = "invalid" | "not_found" | "forbidden" | "unavailable" | "conflict" | "failed" | "offline";
+export type ServerFrame = {
+    t: "welcome";
+    id: number;
+    principal: string;
+    epoch: string;
+    seq: number;
+    schema_hash: string;
+    resync: boolean;
+    protocol?: number;
+    features?: string[];
+}
+/** The server swapped to a reloaded API: every collection and record interest is gone. */
+ | {
+    t: "resync";
+    epoch: string;
+    seq: number;
+    schema_hash: string;
+} | {
+    t: "rows";
+    id: number;
+    sub: number;
+    table: string;
+    start: number;
+    ids: string[];
+    records: WireRecord[];
+    total: number | null;
+    complete: boolean;
+    seq: number;
+} | {
+    t: "members";
+    id?: number;
+    sub: number;
+    start: number;
+    ids: string[];
+    records: WireRecord[];
+    total: number | null;
+    complete: boolean;
+} | {
+    t: "records";
+    id: number;
+    table: string;
+    records: WireRecord[];
+    missing: string[];
+} | {
+    t: "changed";
+    seq: number;
+    events: ChangeEvent[];
+} | {
+    t: "flashed";
+    id: number;
+    rid: string;
+    seq: number;
+    record: WireRecord | null;
+} | {
+    t: "rejected";
+    id: number;
+    message: string;
+    field_errors?: Record<string, string>;
+} | {
+    t: "batch_result";
+    id: number;
+    results: ({
+        t: "flashed";
+        id: number;
+        rid: string;
+        seq: number;
+        record: WireRecord | null;
+    } | {
+        t: "rejected";
+        id: number;
+        message: string;
+        field_errors?: Record<string, string>;
+    })[];
+}
+/** The answer to `invoke`; the run's frames follow. */
+ | {
+    t: "result";
+    id: number;
+    run: string;
+    status: "started" | "attached" | "done";
+} | {
+    t: "options_result";
+    id: number;
+    items: {
+        value: Json;
+        label: string;
+    }[];
+}
+/** `code` names errors a client acts on: `protocol`, `unknown_frame`, and a run's {@link RunCode}. */
+ | {
+    t: "error";
+    id: number;
+    kind: ErrorKind;
+    message: string;
+    code?: string;
+} | {
+    t: "pong";
+    id: number;
+}
+/** The frontend the server serves changed: reload the page. */
+ | {
+    t: "reload";
+}
+/** `run_set` or `run_cancel` was applied. */
+ | {
+    t: "ack";
+    id: number;
+}
+/** What a run did; the first after `invoke` is a snapshot. */
+ | RunFrame;
+export type RunStatus = "running" | "done" | "failed" | "cancelled";
+export type RunCode = "conflict" | "expired" | "forbidden" | "invalid" | "limit" | "failed";
+export interface RunFrame {
+    t: "run";
+    run: string;
+    seq: number;
+    status?: RunStatus;
+    state?: Record<string, Json>;
+    /** Each with the seq it was first sent with; older servers leave it out. */
+    messages?: {
+        name: string;
+        payload: Json;
+        seq?: number;
+    }[];
+    result?: Json;
+    error?: {
+        code: RunCode;
+        message: string;
+    };
+}
+export type FlashItem = {
+    table: string;
+    rid?: string;
+    patch: Record<string, unknown>;
+};
+export type ClientFrame = {
+    t: "hello";
+    protocol: number;
+    token?: string;
+    cursor?: Cursor;
+    schema_hash?: string;
+    features?: string[];
+} | ({
+    t: "open_table";
+} & CollectionSpec) | {
+    t: "viewport";
+    sub: number;
+    start: number;
+    count: number;
+} | {
+    t: "close";
+    sub: number;
+} | {
+    t: "open_records";
+    table: string;
+    ids: string[];
+} | {
+    t: "interest";
+    remove: [string, string][];
+} | ({
+    t: "flash";
+} & FlashItem) | {
+    t: "batch";
+    items: FlashItem[];
+} | {
+    t: "delete";
+    table: string;
+    rid: string;
+}
+/** Start run `run` of `action`, or attach to it; without `action`, attach only. */
+ | {
+    t: "invoke";
+    run: string;
+    action?: string;
+    rid?: string;
+    args?: Record<string, unknown>;
+} | {
+    t: "options";
+    action: string;
+    field: string;
+    form?: Record<string, unknown>;
+} | {
+    t: "run_set";
+    run: string;
+    name: string;
+    value: Json;
+} | {
+    t: "run_cancel";
+    run: string;
+} | {
+    t: "ping";
+};

package/dist/protocol.js

@@ -0,0 +1,5 @@
+// Wire frames (mirror of vantage-server `src/protocol.rs`).
+/** The wire protocol this client speaks; sent in `hello`. */
+export const PROTOCOL = 1;
+/** What this client understands beyond the protocol; sent in `hello`. */
+export const FEATURES = ["runs:1"];

package/dist/react.d.ts

@@ -0,0 +1,59 @@
+import { type FunctionComponent, type ReactNode } from "react";
+import type { VantageDb } from "./client.js";
+import type { ActionResult, CollectionWindow, Connection, LazyCollection, LazyReference, Model, Presence, SchemaTypes, Servo } from "./types.js";
+export { useRun, useRunMessage, useShared } from "./run/hooks.js";
+/** Provide the client. With `fallback`, children wait for `instant` tables. */
+export declare function VantageProvider({ db, fallback, children }: {
+    db: VantageDb<any>;
+    fallback?: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useVantage<S extends SchemaTypes>(): VantageDb<S>;
+/** Re-render `Component` when anything it read during render changes. Generic components keep their type. */
+export declare function observer<C extends FunctionComponent<any>>(Component: C): C;
+/** The value of `fn`, re-computed when what it reads changes. */
+export declare function useLive<T>(fn: () => T, deps?: unknown[]): T;
+/** A collection's rows (models), live; `error` is the server's message when it refused the collection. */
+export declare function useCollection<T>(collection: LazyCollection<T>): {
+    items: readonly T[];
+} & Pick<LazyCollection<T>, "loadState" | "total" | "totalExact" | "length" | "error">;
+/** One window of a collection, for virtualised lists; `error` as in `useCollection`. */
+export declare function useWindow<T>(collection: LazyCollection<T>, start: number, count: number): CollectionWindow<T>;
+/**
+ * A reference's record (`undefined` until loaded), its load `status`, and
+ * `error`, the server's message when it refused to load it.
+ */
+export declare function useRecord<T>(reference: LazyReference<T>): {
+    value: T | undefined;
+    status: Presence;
+    error: string | null;
+};
+/** A draft of `model` for a form; a new draft when the model changes. */
+export declare function useServo<M extends Model>(model: M): Servo<M>;
+/** Wrap an action for a button: `run`, `pending`, the last `error`. */
+export declare function useAction<A extends unknown[], R>(fn: (...args: A) => Promise<ActionResult<R>>): {
+    run: (...args: A) => Promise<ActionResult<R>>;
+    pending: boolean;
+    error: import("./types.js").ActionError | null;
+};
+/**
+ * Suspend until `target` (a model, reference or collection) has loaded
+ * `keys`; then return it. Wrap the component in <Suspense>.
+ */
+export declare function useHydrated<T>(target: T, keys?: readonly string[]): T;
+/** The connection's `status`, whether it `halted` (`refused` or `protocol_mismatch`), and then the server's `error`. */
+export declare function useConnection(): Connection & {
+    seq: number;
+    principal: string | null;
+};
+/**
+ * Start `load` when the pointer rests on (or focus reaches) an element for
+ * `delay` ms — by the click, the data is usually there.
+ *   <a {...usePreloadOnIntent(() => db.bakery.ref(id).load())} href=…>
+ */
+export declare function usePreloadOnIntent(load: () => unknown, delay?: number): {
+    onPointerEnter: () => void;
+    onPointerLeave: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+};

package/dist/react.js

@@ -0,0 +1,169 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// React bindings.
+//
+// `observer(Component)` tracks what a render reads (fields, references,
+// collections) and re-renders on exactly those changes, through
+// `useSyncExternalStore` — tear-free under concurrent rendering, correct in
+// StrictMode. Hooks cover code that prefers explicit subscriptions.
+import { createContext, memo, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { Reaction } from "./signal.js";
+export { useRun, useRunMessage, useShared } from "./run/hooks.js";
+const Context = createContext(null);
+/** Provide the client. With `fallback`, children wait for `instant` tables. */
+export function VantageProvider({ db, fallback, children }) {
+    const [ready, setReady] = useState(fallback === undefined);
+    useEffect(() => {
+        let live = true;
+        void db.ready.then(() => live && setReady(true));
+        return () => {
+            live = false;
+        };
+    }, [db]);
+    return _jsx(Context.Provider, { value: db, children: ready ? children : fallback });
+}
+export function useVantage() {
+    const db = useContext(Context);
+    if (!db)
+        throw new Error("vantage: useVantage() outside <VantageProvider>");
+    return db;
+}
+/** Re-render `Component` when anything it read during render changes. Generic components keep their type. */
+export function observer(Component) {
+    const Observed = (props) => {
+        const reaction = useRef(null);
+        reaction.current ??= new Reaction();
+        useSyncExternalStore(reaction.current.subscribe, reaction.current.getVersion, reaction.current.getVersion);
+        return reaction.current.track(() => Component(props));
+    };
+    Observed.displayName = `observer(${Component.displayName ?? Component.name ?? "Component"})`;
+    return memo(Observed);
+}
+/** The value of `fn`, re-computed when what it reads changes. */
+export function useLive(fn, deps = []) {
+    const reaction = useMemo(() => new Reaction(), []);
+    const cache = useRef(null);
+    const read = useCallback(() => {
+        const c = cache.current;
+        if (!c || c.version !== reaction.version || !sameDeps(c.deps, deps)) {
+            cache.current = { version: reaction.version, value: reaction.track(fn), deps };
+        }
+        return cache.current.value;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [reaction, ...deps]);
+    return useSyncExternalStore(reaction.subscribe, read, read);
+}
+/** A collection's rows (models), live; `error` is the server's message when it refused the collection. */
+export function useCollection(collection) {
+    return useLive(() => ({
+        items: collection.elements,
+        loadState: collection.loadState,
+        total: collection.total,
+        totalExact: collection.totalExact,
+        length: collection.length,
+        error: collection.error,
+    }), [key(collection)]);
+}
+/** One window of a collection, for virtualised lists; `error` as in `useCollection`. */
+export function useWindow(collection, start, count) {
+    return useLive(() => collection.window(start, count), [key(collection), start, count]);
+}
+/**
+ * A reference's record (`undefined` until loaded), its load `status`, and
+ * `error`, the server's message when it refused to load it.
+ */
+export function useRecord(reference) {
+    return useLive(() => ({ value: reference.value, status: reference.status, error: reference.error }), [reference]);
+}
+/** A draft of `model` for a form; a new draft when the model changes. */
+export function useServo(model) {
+    const servo = useMemo(() => model.edit(), [model]);
+    useLive(() => {
+        // Read the draft's tracked parts so the form re-renders as it changes.
+        void servo.$isDirty;
+        void servo.$status;
+        void servo.$errors;
+        return null;
+    }, [servo]);
+    return servo;
+}
+/** Wrap an action for a button: `run`, `pending`, the last `error`. */
+export function useAction(fn) {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    const latest = useRef(fn);
+    latest.current = fn;
+    const run = useCallback(async (...args) => {
+        setPending(true);
+        setError(null);
+        const result = await latest.current(...args);
+        setPending(false);
+        if (!result.ok)
+            setError(result.error);
+        return result;
+    }, []);
+    return { run, pending, error };
+}
+/**
+ * Suspend until `target` (a model, reference or collection) has loaded
+ * `keys`; then return it. Wrap the component in <Suspense>.
+ */
+export function useHydrated(target, keys) {
+    const promise = hydrationOf(target, keys);
+    if (!promise.done)
+        throw promise.wait;
+    if (promise.error)
+        throw promise.error;
+    return (promise.value ?? target);
+}
+const hydrations = new WeakMap();
+function hydrationOf(target, keys) {
+    const obj = target;
+    let perKeys = hydrations.get(obj);
+    if (!perKeys)
+        hydrations.set(obj, (perKeys = new Map()));
+    const k = (keys ?? ["*"]).join(",");
+    let h = perKeys.get(k);
+    if (!h) {
+        const entry = { wait: Promise.resolve(), done: false };
+        const start = obj.hydrate ? obj.hydrate(keys) : obj.load ? obj.load() : Promise.resolve(obj);
+        entry.wait = start.then((value) => {
+            entry.value = value;
+            entry.done = true;
+        }, (error) => {
+            entry.error = error;
+            entry.done = true;
+        });
+        perKeys.set(k, (h = entry));
+    }
+    return h;
+}
+/** The connection's `status`, whether it `halted` (`refused` or `protocol_mismatch`), and then the server's `error`. */
+export function useConnection() {
+    const db = useVantage();
+    return useLive(() => ({ ...db.connection.get(), seq: db.seq.get(), principal: db.principal.get() }));
+}
+/**
+ * Start `load` when the pointer rests on (or focus reaches) an element for
+ * `delay` ms — by the click, the data is usually there.
+ *   <a {...usePreloadOnIntent(() => db.bakery.ref(id).load())} href=…>
+ */
+export function usePreloadOnIntent(load, delay = 60) {
+    const timer = useRef(undefined);
+    const latest = useRef(load);
+    latest.current = load;
+    const db = useContext(Context);
+    return useMemo(() => {
+        const start = () => {
+            clearTimeout(timer.current);
+            timer.current = setTimeout(() => void (db ? db.preload(latest.current) : latest.current()), delay);
+        };
+        const cancel = () => clearTimeout(timer.current);
+        return { onPointerEnter: start, onPointerLeave: cancel, onFocus: start, onBlur: cancel };
+    }, [db, delay]);
+}
+function key(collection) {
+    return JSON.stringify(collection.spec ?? null);
+}
+function sameDeps(a, b) {
+    return a.length === b.length && a.every((x, i) => Object.is(x, b[i]));
+}

package/dist/reserved.d.ts

@@ -0,0 +1,6 @@
+export type Member = {
+    kind: "column" | "reference" | "action";
+    name: string;
+};
+/** The first member of `entity` that takes a reserved name, as a one-line message. */
+export declare function reservedClash(entity: string, members: Member[]): string | undefined;

package/dist/reserved.js

@@ -0,0 +1,13 @@
+// Names a model keeps for itself. A column, reference or row action can't
+// take one, or it would hide the model's own member: `id`, `edit`, `patch`,
+// `delete`, `hydrate`, and anything starting with `$` (`$status`,
+// `$actions`, …). The id column itself is named `id`, and hidden columns
+// aren't on the model, so neither clashes.
+const RESERVED = new Set(["id", "edit", "patch", "delete", "hydrate"]);
+/** The first member of `entity` that takes a reserved name, as a one-line message. */
+export function reservedClash(entity, members) {
+    const clash = members.find((m) => RESERVED.has(m.name) || m.name.startsWith("$"));
+    if (!clash)
+        return undefined;
+    return `entity \`${entity}\`: ${clash.kind} \`${clash.name}\` clashes with a name the model reserves (id, edit, patch, delete, hydrate, $…); rename it in the API`;
+}

package/dist/run/frames.d.ts

@@ -0,0 +1,6 @@
+import type { RunFrame } from "../protocol.js";
+export type FrameKind = "snapshot" | "live" | "stale" | "gap";
+/** How to treat `frame` for a run that has applied frames up to `lastSeq` (-1: none yet). */
+export declare function classify(frame: RunFrame, lastSeq: number): FrameKind;
+/** A run that ended, by the frame's status. A status this client doesn't know is not an end. */
+export declare function isFinal(frame: RunFrame): boolean;

package/dist/run/frames.js

@@ -0,0 +1,24 @@
+// Reading `run` frames: which are snapshots, which are live, and when one
+// was missed. Unknown fields are ignored, so a newer server's frames still
+// apply.
+//
+// The server numbers a run's frames with `seq`. The first frame after an
+// invoke or attach is a snapshot: the whole state, the buffered messages
+// and the status. Each later frame carries one change. A frame whose seq
+// skips ahead means one was lost: the client attaches again for a fresh
+// snapshot.
+/** How to treat `frame` for a run that has applied frames up to `lastSeq` (-1: none yet). */
+export function classify(frame, lastSeq) {
+    const snapshot = frame.status !== undefined && frame.state !== undefined && frame.messages !== undefined;
+    if (snapshot)
+        return frame.seq < lastSeq ? "stale" : "snapshot";
+    if (lastSeq < 0)
+        return "gap"; // a live frame before any snapshot
+    if (frame.seq <= lastSeq)
+        return "stale";
+    return frame.seq === lastSeq + 1 ? "live" : "gap";
+}
+/** A run that ended, by the frame's status. A status this client doesn't know is not an end. */
+export function isFinal(frame) {
+    return frame.status === "done" || frame.status === "failed" || frame.status === "cancelled";
+}

package/dist/run/hooks.d.ts

@@ -0,0 +1,18 @@
+import type { ActionResult } from "../types.js";
+import type { MessagesOf, Run, RunFactory, RunTypes } from "./types.js";
+/**
+ * One run of `factory`'s action for this component: idle until `start`.
+ * With `key`, its id is kept in `sessionStorage` (per action), so after a
+ * page reload the same component attaches to the run again; a stored run
+ * the server no longer has (expired, or never yours) is forgotten and the
+ * run is back to `idle`. `run.forget()` forgets it too.
+ */
+export declare function useRun<T extends RunTypes>(factory: RunFactory<T>, options?: {
+    key?: string;
+}): Run<T>;
+type Shared<T extends RunTypes, K extends keyof T["state"]> = K extends keyof T["inputs"] ? [value: T["state"][K], set: (value: T["state"][K]) => Promise<ActionResult<undefined>>] : T["state"][K];
+/** A run's variable, live; for an input, `[value, set]`. */
+export declare function useShared<T extends RunTypes, K extends keyof T["state"] & string>(run: Run<T>, name: K): Shared<T, K>;
+/** Call `fn` for each message `name` the run sends while mounted, in order; `vantage.notify` is a body's `notify(text)`. */
+export declare function useRunMessage<T extends RunTypes, K extends keyof MessagesOf<T> & string>(run: Run<T>, name: K, fn: (payload: MessagesOf<T>[K]) => void): void;
+export {};