@vantage-ui/client 0.0.0-stage → 0.4.3

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.4.3 — 2026-10-13
+
+- A run delivers to `on`/`useRunMessage` the messages sent while the connection was down or across a `resync`, from the server's `seq` on each message.
+
+## 0.4.2 — 2026-10-13
+
+- MockServer fixture `actions` also accept a project action's YAML key with dashes (`check-overdue` for `check_overdue`); naming one action both ways throws.
+- Docs: fixture action keys are wire names, handlers are typed with `ActionHandler` and `MockRunControl`, and `run.start()` on a finished run begins a new run.
+- Docs: rebuilding a list from `run.messages` after a reload, `start()` with no argument, and why `XFields` columns are nullable.
+
+## 0.4.1 — 2026-10-13
+
+- `db.reconnect()` connects again after `refused`, calling `token` afresh, for a sign-in form.
+- The generated file's header says how it is regenerated: by the web dev container from `schema.json`, or with `npx vantage-client generate`.
+
+## 0.4.0 — 2026-10-13
+
+- Actions run as runs: `db.run.<action>` and `model.$run.<action>` give `start(args, { run? })`, `attach(id)` and `idle()`; a `Run` has reactive `status`, `state`, `result`, `error` and `messages`, plus `on`, `set` (inputs, optimistic), `cancel` and `done`. Breaking: `db.run.x(input)` is now `db.run.x.start(input)`.
+- Row and toolbar action methods run the action and wait for its end; they no longer return the server's record.
+- React: `useRun(factory, { key })` (re-attaches after a page reload), `useShared` and `useRunMessage`.
+- `generate` emits `<Action>Run` (`args`, `state`, `inputs`, `messages`) per action and `$run` on models; the runtime schema carries each action's `state` and `messages`.
+- `hello` sends `features: ["runs:1"]`; a server without it fails runs with a clear message. An unanswered `start` is sent again with the same id after a reconnect or `resync`, and running runs attach again; unknown frames, fields and statuses are ignored.
+- `run.on`/`useRunMessage` take `vantage.notify` and `vantage.log`; `run.forget()` returns a run to `idle`; `useRun` keys are scoped to the action.
+- Removed: `db.jobs`, `stopJob`, `useJobs`, the `Job` type and `ActionResult.job`.
+- MockServer runs action handlers as runs (`(row, args, run)`), with `server.runs`.
+
+## 0.3.0 — 2026-10-13
+
+- Connects to `/v1/ws` on the page's origin by default; outside a browser a `url` is required.
+- `hello` sends `protocol: 1` and the `token` option.
+- `db.connection` is `{ status, halted, error? }`: `online`/`offline` became `open`/`closed`, plus final `refused` and `protocol_mismatch` (`halted`); `db.ready` settles on them and resolves with the connection. `useConnection()` returns `halted` too.
+- `resync` reopens what is shown without flashing rows; refusals land on `error` and are not retried.
+- `useRecord` returns `{ value, status, error }`; collections and windows carry `error`.
+- Windows add `total`, `totalExact`, `settled`, `length`, `lengthExact` and `whenLoaded()`; collections and `useCollection` add `totalExact`.
+- The same collection description gives the same object while it is in use.
+- Removed: `filter`/`find`/`some`/`every` on collections, and the root exports `Reaction`, `track`, `untracked`, `WebSocketTransport`, `defaultUrl`, `PROTOCOL`, `uuidv7` and `DraftFields`. `Vantage` is exported as a type only, and internal members are left out of the published types.
+- `observer` keeps a generic component's type.
+- MockServer adds `opened` and `refuseWrites`/`allowWrites`.
+- Edits queued while offline are sent on reconnect in the same page only; a reload loses them.
+- Draft members are `$`-prefixed (`$flash`, `$isDirty`, `$status`, `$errors`, `$dirty`, `$revert`); columns, references and row actions with reserved names are refused.
+- `npx vantage-client generate --from <url | file>` replaces the Rust `generate-ts`; it reads the running server's `/v1/schema` directly.
+- Development runs on local Node 22+; no Docker.
+- The generated `schema` carries `sortable`, `filter`, `defaultSort` (`{ column, direction }`) and each enum column's values; labels in generated comments are escaped.
+- Ships an ESM build with types, the `generate` CLI, and the `vantage-client` skill.

package/bin/vantage-client.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// `npx @vantage-ui/client generate --from <url-or-file> --out <file>`
+import { main } from "../dist/codegen/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/dist/client-connection.d.ts

@@ -0,0 +1,41 @@
+import { ClientRuns } from "./client-runs.js";
+import type { Connection } from "./types.js";
+export declare class ClientConnection extends ClientRuns {
+    /** Bumps on every connect: events from an earlier socket are ignored. */
+    private attempt;
+    /** `reconnect()` calls waiting for the attempt to open or be refused. */
+    private reconnecting;
+    /**
+     * Connect again after the server refused this client, calling `token`
+     * afresh: what a sign-in form does once the user has entered a new token.
+     * Collections and records the refusal failed get another try. Resolves
+     * like `ready` does, once the new connection has loaded the `instant`
+     * tables or has been refused again. Only `refused` reconnects; in any
+     * other state this resolves with the connection as it is.
+     */
+    reconnect(): Promise<Connection>;
+    /** Answer the `reconnect()` calls waiting on this attempt. */
+    private settleReconnect;
+    protected start(): Promise<void>;
+    private connect;
+    private hello;
+    /**
+     * Reopen every collection that is pinned or shown, and send the record
+     * loads queued meanwhile. With `reload`, loaded records outside the shown
+     * collections are fetched again too. Rows on screen stay until their fresh
+     * copies arrive; records already loading keep their request.
+     */
+    private reopen;
+    /** The server swapped to a reloaded API: follow its new journal and reopen what is shown. */
+    private resync;
+    private checkSchema;
+    /**
+     * A final answer from the server: stop, don't reconnect, and settle
+     * everything waiting (`ready`, collection and record loads, queued writes)
+     * with `error`, writes queued offline included.
+     */
+    private halt;
+    private lost;
+    private receive;
+    private applyChange;
+}

package/dist/client-connection.js

@@ -0,0 +1,260 @@
+// The connection lifecycle: connect and `hello`, reconnect with backoff,
+// the final `refused`/`protocol_mismatch` states, `resync` after an API
+// reload, and the server-pushed frames (`changed`, `members`, `run`,
+// `reload`).
+import { ClientRuns } from "./client-runs.js";
+import { FEATURES, PROTOCOL } from "./protocol.js";
+import { batch } from "./signal.js";
+export class ClientConnection extends ClientRuns {
+    /** Bumps on every connect: events from an earlier socket are ignored. */
+    attempt = 0;
+    /** `reconnect()` calls waiting for the attempt to open or be refused. */
+    reconnecting = [];
+    /**
+     * Connect again after the server refused this client, calling `token`
+     * afresh: what a sign-in form does once the user has entered a new token.
+     * Collections and records the refusal failed get another try. Resolves
+     * like `ready` does, once the new connection has loaded the `instant`
+     * tables or has been refused again. Only `refused` reconnects; in any
+     * other state this resolves with the connection as it is.
+     */
+    reconnect() {
+        if (this.connection.peek().status !== "refused")
+            return Promise.resolve(this.connection.peek());
+        const settled = new Promise((resolve) => this.reconnecting.push(resolve));
+        this.closed = false;
+        this.retry = 0;
+        for (const cell of this.collections.values())
+            cell.reset();
+        for (const cell of this.store.allCells())
+            if (cell.presence.peek() === "error")
+                cell.presence.set("none");
+        this.sweeper = setInterval(() => this.sweep(), 5_000);
+        this.connect();
+        return settled;
+    }
+    /** Answer the `reconnect()` calls waiting on this attempt. */
+    settleReconnect() {
+        const connection = this.connection.peek();
+        for (const resolve of this.reconnecting.splice(0))
+            resolve(connection);
+    }
+    async start() {
+        if (this.storage) {
+            const saved = await this.storage.load().catch(() => undefined);
+            if (saved) {
+                batch(() => {
+                    for (const { table, record } of saved.records) {
+                        if (this.schema.tables[table]?.persist)
+                            this.store.cell(table, record.id).applyServer(record, "stale");
+                    }
+                });
+                this.cursor = saved.cursor ?? undefined;
+                this.outbox = saved.outbox ?? [];
+            }
+        }
+        this.connect();
+    }
+    connect() {
+        if (this.closed)
+            return;
+        this.setStatus("connecting");
+        const attempt = ++this.attempt;
+        const current = () => attempt === this.attempt;
+        this.transport.connect({
+            open: () => current() && void this.hello(),
+            message: (frame) => current() && this.receive(frame),
+            close: (code, reason) => current() && this.lost(code, reason),
+        });
+    }
+    async hello() {
+        let token;
+        try {
+            token = typeof this.opts.token === "function" ? await this.opts.token() : this.opts.token;
+        }
+        catch (e) {
+            return this.halt("refused", e instanceof Error ? e.message : String(e));
+        }
+        const welcome = await this.request({ t: "hello", protocol: PROTOCOL, token, cursor: this.cursor, schema_hash: this.schema.hash, features: FEATURES }, true);
+        if (welcome.t === "error" && welcome.kind === "offline")
+            return; // lost mid-hello: the reconnect says hello again
+        if (welcome.t === "error" && welcome.code === "protocol")
+            return this.halt("protocol_mismatch", welcome.message);
+        if (welcome.t !== "welcome")
+            return this.halt("refused", welcome.t === "error" ? welcome.message : `unexpected reply \`${welcome.t}\``);
+        if (welcome.protocol !== undefined && welcome.protocol !== PROTOCOL) {
+            return this.halt("protocol_mismatch", `the server speaks protocol ${welcome.protocol}, this client ${PROTOCOL}`);
+        }
+        this.checkSchema(welcome.schema_hash);
+        this.retry = 0;
+        this.cursor = { epoch: welcome.epoch, seq: welcome.seq };
+        this.principal.set(welcome.principal);
+        this.features = new Set(welcome.features ?? []);
+        this.setStatus("open");
+        this.resumeRuns();
+        // Bootstrap: instant tables load whole and stay open.
+        const instant = Object.entries(this.schema.tables)
+            .filter(([, meta]) => meta.load === "instant")
+            .map(([name]) => this.collectionCell({ table: name }));
+        for (const cell of instant)
+            cell.pinned = true;
+        await this.reopen(welcome.resync);
+        this.markReady();
+        this.settleReconnect();
+        // Edits made offline go out now, in order.
+        const queued = this.flashQueue.splice(0);
+        if (queued.length) {
+            this.flashQueue = queued;
+            void this.flush();
+        }
+    }
+    /**
+     * Reopen every collection that is pinned or shown, and send the record
+     * loads queued meanwhile. With `reload`, loaded records outside the shown
+     * collections are fetched again too. Rows on screen stay until their fresh
+     * copies arrive; records already loading keep their request.
+     */
+    async reopen(reload) {
+        const shown = [...this.collections.values()].filter((c) => !c.refused && (c.pinned || c.wanted()));
+        await Promise.all(shown.map((c) => c.open()));
+        if (reload) {
+            const inCollections = new Set(shown.flatMap((c) => c.ids.peek().map((id) => `${c.spec.table}\u0000${id}`)));
+            const held = new Map();
+            for (const cell of this.store.allCells()) {
+                if (cell.presence.peek() === "loaded" && !inCollections.has(`${cell.table}\u0000${cell.id}`)) {
+                    held.set(cell.table, [...(held.get(cell.table) ?? []), cell.id]);
+                }
+            }
+            for (const [table, ids] of held)
+                void this.reloadRecords(table, ids);
+        }
+        if (this.loadQueue.size)
+            void this.flushLoads();
+    }
+    /** The server swapped to a reloaded API: follow its new journal and reopen what is shown. */
+    resync(frame) {
+        this.checkSchema(frame.schema_hash);
+        this.generation++;
+        this.cursor = { epoch: frame.epoch, seq: frame.seq };
+        this.seq.set(frame.seq);
+        this.persistCursor();
+        this.bySub.clear();
+        // The reloaded API may allow what the old one refused: collections and records get one more try.
+        for (const cell of this.collections.values())
+            cell.reset();
+        for (const cell of this.store.allCells())
+            if (cell.presence.peek() === "error")
+                cell.presence.set("none");
+        void this.reopen(true);
+        // An invoke answered around the reload may not stream; asking again does.
+        this.resumeRuns();
+    }
+    checkSchema(hash) {
+        if (hash !== this.schema.hash) {
+            console.warn(`vantage: client types were generated from schema ${this.schema.hash}, server runs ${hash} — regenerate vantage.gen.ts`);
+        }
+    }
+    /**
+     * A final answer from the server: stop, don't reconnect, and settle
+     * everything waiting (`ready`, collection and record loads, queued writes)
+     * with `error`, writes queued offline included.
+     */
+    halt(status, error) {
+        this.setStatus(status, error);
+        this.close();
+        const kind = status === "refused" ? "forbidden" : "unavailable";
+        for (const { resolve } of this.flashQueue.splice(0))
+            resolve({ t: "error", id: 0, kind, message: error });
+        for (const cell of this.collections.values()) {
+            const state = cell.loadState.peek();
+            // Unloaded cells, and windows still waiting for rows (a viewport in flight).
+            if (state === "idle" || state === "loading" || cell.waitingForWindow)
+                cell.failed(error);
+        }
+        for (const [table, ids] of this.loadQueue) {
+            for (const id of ids) {
+                this.store.cell(table, id).refused(error);
+                this.wake(table, id);
+            }
+        }
+        this.loadQueue.clear();
+        this.markReady();
+        this.settleReconnect();
+    }
+    lost(code, reason) {
+        for (const resolve of this.requests.values())
+            resolve({ t: "error", id: 0, kind: "offline", message: "connection lost" });
+        this.requests.clear();
+        for (const cell of this.collections.values())
+            cell.sub = null;
+        this.bySub.clear();
+        const halted = this.haltedWith !== undefined;
+        // 1008 (policy violation): the reloaded API refuses this client's token.
+        if (code === 1008 && !halted)
+            return this.halt("refused", reason || "the server refused this client");
+        if (halted)
+            return;
+        this.setStatus("closed");
+        if (this.closed)
+            return;
+        const delay = Math.min(10_000, 200 * 2 ** this.retry++);
+        setTimeout(() => this.connect(), delay);
+    }
+    receive(frame) {
+        if ("id" in frame && frame.id && this.requests.has(frame.id)) {
+            const resolve = this.requests.get(frame.id);
+            this.requests.delete(frame.id);
+            resolve(frame);
+            return;
+        }
+        // Frames of a type this client doesn't know (a newer server's) fall through.
+        switch (frame.t) {
+            case "changed":
+                batch(() => frame.events.forEach((e) => this.applyChange(e)));
+                if (frame.seq && this.cursor) {
+                    this.cursor = { ...this.cursor, seq: Math.max(this.cursor.seq, frame.seq) };
+                    this.seq.set(this.cursor.seq);
+                    this.persistCursor();
+                }
+                break;
+            case "members":
+                this.applyMembers(frame);
+                break;
+            case "resync":
+                this.resync(frame);
+                break;
+            case "run":
+                this.onRun(frame);
+                break;
+            case "reload":
+                if (this.opts.onReload)
+                    this.opts.onReload();
+                else if (typeof globalThis.location?.reload === "function")
+                    globalThis.location.reload();
+                break;
+        }
+    }
+    applyChange(event) {
+        if (event.k === "upsert") {
+            const cell = this.store.cell(event.table, event.id);
+            cell.applyServer(event.record);
+            this.persistLater(cell);
+        }
+        else if (event.k === "removed") {
+            const cell = this.store.peek(event.table, event.id);
+            if (cell) {
+                cell.markRemoved();
+                this.persistLater(cell);
+            }
+            for (const c of this.collections.values())
+                if (c.spec.table === event.table)
+                    c.drop(event.id);
+        }
+        else {
+            for (const c of this.collections.values()) {
+                if (c.spec.table === event.table && c.sub !== null)
+                    void this.openCollection(c);
+            }
+        }
+    }
+}

package/dist/client-core.d.ts

@@ -0,0 +1,70 @@
+import type { Vantage, VantageOptions } from "./client.js";
+import type { CollectionCell } from "./collection-cell.js";
+import type { Collection } from "./collection.js";
+import { type AnyModel } from "./model.js";
+import type { ClientFrame, Cursor, FlashItem, ServerFrame } from "./protocol.js";
+import type { Storage } from "./persist.js";
+import { State } from "./signal.js";
+import { type RecordCell } from "./store.js";
+import type { TableHandle } from "./table.js";
+import { type Transport } from "./transport.js";
+import type { Connection, ConnectionStatus, SchemaMeta } from "./types.js";
+type Pending = (frame: ServerFrame) => void;
+export declare class ClientCore {
+    readonly connection: State<Connection>;
+    readonly principal: State<string | null>;
+    readonly seq: State<number>;
+    /**
+     * Resolves with the connection once `instant` tables have loaded for the
+     * first time, or once the server refused the client for good (`halted`).
+     */
+    readonly ready: Promise<Connection>;
+    readonly schema: SchemaMeta;
+    protected transport: Transport;
+    protected opts: VantageOptions;
+    protected storage?: Storage;
+    protected models: Map<RecordCell, AnyModel>;
+    protected classes: Map<string, new (cell: RecordCell) => AnyModel>;
+    protected collections: Map<string, CollectionCell>;
+    /** One Collection per description, kept while one of its cells is. */
+    protected interned: Map<string, Collection>;
+    protected bySub: Map<number, CollectionCell>;
+    protected handles: Map<string, TableHandle<any, any, any>>;
+    protected requests: Map<number, Pending>;
+    protected nextId: number;
+    protected cursor?: Cursor;
+    protected loadQueue: Map<string, Set<string>>;
+    protected loadWaiters: Map<string, (() => void)[]>;
+    protected flashQueue: {
+        item: FlashItem;
+        resolve: (frame: ServerFrame) => void;
+    }[];
+    protected outbox: FlashItem[];
+    protected undoStack: {
+        table: string;
+        id: string;
+        before: Record<string, unknown>;
+        after: Record<string, unknown>;
+    }[];
+    protected retry: number;
+    /** Bumps on every `resync`: replies to frames sent before it are stale. */
+    protected generation: number;
+    protected closed: boolean;
+    protected sweeper?: ReturnType<typeof setInterval>;
+    private resolveReady;
+    protected persistTimer?: ReturnType<typeof setTimeout>;
+    protected dirtyCells: Set<RecordCell>;
+    constructor(options: VantageOptions);
+    /** Settle `ready` with the connection as it is now; later calls change nothing. */
+    protected markReady(): void;
+    /** This client as the typed `Vantage` the models and collections hold. */
+    protected get db(): Vantage<any>;
+    close(): void;
+    protected get online(): boolean;
+    protected setStatus(status: ConnectionStatus, error?: string): void;
+    protected send(frame: ClientFrame): void;
+    protected persistLater(cell: RecordCell): void;
+    protected persistCursor(): void;
+    private modelClass;
+}
+export {};

package/dist/client-core.js

@@ -0,0 +1,140 @@
+// The client's state and plumbing: the transport and request routing, the
+// connection status, persistence, and the model instances. The layers on
+// top (loading, writes, connection) and `Vantage` itself extend it.
+import { buildModelClass } from "./model.js";
+import { State } from "./signal.js";
+import { Store } from "./store.js";
+import { WebSocketTransport, defaultUrl } from "./transport.js";
+export class ClientCore {
+    /** @internal */ store = new Store();
+    connection = new State({ status: "connecting", halted: false });
+    principal = new State(null);
+    seq = new State(0);
+    /**
+     * Resolves with the connection once `instant` tables have loaded for the
+     * first time, or once the server refused the client for good (`halted`).
+     */
+    ready;
+    schema;
+    transport;
+    opts;
+    storage;
+    models = new Map();
+    classes = new Map();
+    collections = new Map();
+    /** One Collection per description, kept while one of its cells is. */
+    interned = new Map();
+    bySub = new Map();
+    handles = new Map();
+    requests = new Map();
+    nextId = 1;
+    cursor;
+    loadQueue = new Map();
+    loadWaiters = new Map();
+    flashQueue = [];
+    outbox = [];
+    undoStack = [];
+    retry = 0;
+    /** Bumps on every `resync`: replies to frames sent before it are stale. */
+    generation = 0;
+    closed = false;
+    sweeper;
+    resolveReady;
+    persistTimer;
+    dirtyCells = new Set();
+    constructor(options) {
+        this.opts = options;
+        this.schema = options.schema;
+        this.storage = options.storage;
+        this.transport = options.transport ?? new WebSocketTransport(options.url ?? defaultUrl());
+        this.ready = new Promise((resolve) => (this.resolveReady = resolve));
+    }
+    /** Settle `ready` with the connection as it is now; later calls change nothing. */
+    markReady() {
+        this.resolveReady(this.connection.peek());
+    }
+    /** This client as the typed `Vantage` the models and collections hold. */
+    get db() {
+        return this;
+    }
+    /** @internal */ get keepAliveMs() {
+        return this.opts.keepAliveMs ?? 30_000;
+    }
+    close() {
+        this.closed = true;
+        clearInterval(this.sweeper);
+        this.transport.close();
+    }
+    get online() {
+        return this.connection.peek().status === "open";
+    }
+    /** @internal The server's final refusal (`refused`, `protocol_mismatch`), once there is one. */
+    get haltedWith() {
+        const { status, error, halted } = this.connection.peek();
+        return halted ? (error ?? status) : undefined;
+    }
+    setStatus(status, error) {
+        const now = this.connection.peek();
+        if (now.status === status && now.error === error)
+            return;
+        const halted = status === "refused" || status === "protocol_mismatch";
+        this.connection.set(error === undefined ? { status, halted } : { status, halted, error });
+    }
+    /** @internal */ request(frame, force = false) {
+        if (!force && !this.online)
+            return Promise.resolve({ t: "error", id: 0, kind: "offline", message: "not connected" });
+        const id = this.nextId++;
+        return new Promise((resolve) => {
+            this.requests.set(id, resolve);
+            this.transport.send({ ...frame, id });
+        });
+    }
+    send(frame) {
+        this.transport.send(frame);
+    }
+    // ------------------------------------------------------------ persistence
+    persistLater(cell) {
+        if (!this.storage || !this.schema.tables[cell.table]?.persist)
+            return;
+        this.dirtyCells.add(cell);
+        clearTimeout(this.persistTimer);
+        this.persistTimer = setTimeout(() => {
+            const cells = [...this.dirtyCells];
+            this.dirtyCells.clear();
+            void this.storage.save({
+                records: cells.map((c) => ({ table: c.table, id: c.id, record: c.presence.peek() === "missing" ? null : c.baseline })),
+                cursor: this.cursor,
+            });
+        }, 250);
+    }
+    persistCursor() {
+        if (this.storage && this.cursor)
+            void this.storage.save({ cursor: this.cursor });
+    }
+    // ------------------------------------------------------------ models
+    /** @internal The one model instance for (table, id). */
+    model(table, id) {
+        const cell = this.store.cell(table, id);
+        let model = this.models.get(cell);
+        if (!model) {
+            const Class = this.modelClass(table);
+            model = new Class(cell);
+            this.models.set(cell, model);
+        }
+        return model;
+    }
+    /** @internal */ meta(table) {
+        const meta = this.schema.tables[table];
+        if (!meta)
+            throw new Error(`vantage: unknown table \`${table}\``);
+        return meta;
+    }
+    modelClass(table) {
+        let Class = this.classes.get(table);
+        if (!Class) {
+            Class = buildModelClass(this.db, table, this.meta(table));
+            this.classes.set(table, Class);
+        }
+        return Class;
+    }
+}

package/dist/client-loading.d.ts

@@ -0,0 +1,13 @@
+import { ClientCore } from "./client-core.js";
+import type { ServerFrame } from "./protocol.js";
+export declare class ClientLoading extends ClientCore {
+    protected flushLoads(): Promise<void>;
+    protected wake(table: string, id: string): void;
+    /** Close the cell's sub on the server and forget it, so its `members` no longer reach the cell. */
+    private dropSub;
+    protected applyMembers(frame: Extract<ServerFrame, {
+        t: "members";
+    }>): void;
+    /** Close collections and drop records nothing has shown for a while. */
+    protected sweep(): void;
+}