@vantage-ui/client 0.0.0-stage → 0.4.4

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.4.4 — 2026-10-13
+
+- A README for the npm page, plus `keywords` and `homepage`.
+
+## 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/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @vantage-ui/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript client for a [Vantage](https://vantage-ui.com) API. It turns
+the API into typed models. Reads are lazy and stay current: the server pushes
+changes, and a React component re-renders on exactly the fields it read.
+Writes are optimistic and roll back when the server refuses them.
+
+It runs in the browser and in Node 22 or later, and has no runtime
+dependencies. The React bindings need React 18 or later.
+
+```sh
+npm install @vantage-ui/client
+```
+
+## Generate the models
+
+The models come from the API's schema at `/v1/schema`:
+
+```sh
+npx vantage-client generate --from http://127.0.0.1:8090/v1/schema --out src/vantage.gen.ts
+```
+
+`--from` also takes a saved copy of the schema (`schema.json`). Regenerate
+after the API changes; never edit the generated file. Per entity it has
+`XFields` (the record), `XInput` (what `create()` takes) and the model `X`,
+with typed columns, lazy references, has-many collections and a method per
+row action.
+
+## Connect
+
+A page served by the API connects to `/v1/ws` on its own origin:
+
+```ts
+import { createVantage } from "@vantage-ui/client";
+import { schema, type Schema } from "./vantage.gen";
+
+const db = createVantage<Schema>({ schema, token: () => sessionStorage.getItem("vantage.token") ?? undefined });
+```
+
+Outside a browser, pass `url: "ws://127.0.0.1:8090/v1/ws"`. `db.ready`
+resolves once the API's `instant` entities have loaded, and `db.connection`
+reports `connecting`, `open`, `closed` (reconnecting), `refused` or
+`protocol_mismatch`.
+
+## Read
+
+```ts
+const open = db.issues.where({ status: "open" }).sort("created_at", "desc");
+await open.load();
+const titles = open.map((issue) => issue.title);
+
+const page = await db.issues.window(0, 50).whenLoaded(); // one window of a long list
+
+const issue = await db.issues.ref("JIR-12").load();
+const project = await issue?.project; // references load on first read
+```
+
+The server filters, sorts and pages; the API decides which columns may be
+filtered and sorted. A refused query never throws: the collection's `error`
+holds the server's message.
+
+## Write
+
+```ts
+const result = await issue.patch({ status: "done" });
+if (!result.ok) console.warn(result.error.message, issue.$errors);
+
+const draft = issue.edit();
+draft.title = "Login fails on Safari";
+await draft.$flash();
+
+await db.issues.create({ title: "Export to CSV", project: "JIR", status: "open" });
+```
+
+## Actions and runs
+
+Row actions are methods on the model, and `$actions` lists the ones the row
+allows right now. Every action runs as a run, with shared state and messages,
+that survives a reconnect or a page reload without running twice:
+
+```ts
+if (issue.$actions.includes("close_issue")) await issue.close_issue({ resolution: "fixed" });
+
+const run = db.run.triage.start({ project: "JIR" });
+run.on("flagged", (m) => console.warn(`${m.issue} has no assignee`));
+const outcome = await run.done;
+```
+
+## React
+
+```tsx
+import { VantageProvider, observer, useCollection, useVantage } from "@vantage-ui/client/react";
+
+const OpenIssues = observer(() => {
+  const db = useVantage<Schema>();
+  const { items, error } = useCollection(db.issues.where({ status: "open" }));
+  if (error) return <p role="alert">{error}</p>;
+  return <ul>{items.map((issue) => <li key={issue.id}>{issue.title}</li>)}</ul>;
+});
+
+<VantageProvider db={db} fallback={<p>Connecting…</p>}>
+  <OpenIssues />
+</VantageProvider>;
+```
+
+There are also hooks for windows (`useWindow`), records, actions, runs
+(`useRun`, `useShared`, `useRunMessage`) and the connection (`useConnection`).
+
+## Testing
+
+`@vantage-ui/client/testing` has `MockServer`, an in-memory server with no
+network, for unit tests and Storybook:
+
+```ts
+import { createTestVantage } from "@vantage-ui/client/testing";
+
+const { db, server } = createTestVantage<Schema>(schema, {
+  tables: { issues: [{ id: "JIR-1", title: "Login fails", status: "open", project: "JIR" }] },
+  actions: { "issues.close_issue": () => ({ status: "done" }) },
+});
+```
+
+## Full documentation
+
+The package ships an agent skill that is also its reference documentation:
+`skills/vantage-client/SKILL.md`, with `references/react.md`,
+`references/testing.md` and `references/protocol.md`. Every example in it is
+type-checked and run in this package's tests.
+
+## License
+
+MIT

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 {};