@vantage-ui/client 0.0.0-stage → 0.4.3

package/dist/mock-store.d.ts

@@ -0,0 +1,78 @@
+import { type Row } from "./mock-query.js";
+import { MockRun, type MockRunControl } from "./mock-runs.js";
+import type { MockTransport } from "./mock-transport.js";
+import type { ChangeEvent, ClientFrame, CollectionSpec, FlashItem, ServerFrame, WireRecord } from "./protocol.js";
+import type { SchemaMeta } from "./types.js";
+/**
+ * An action's body. What it returns (or resolves to) is the run's result; a
+ * row action's returned object is also applied to the row as a patch. `run`
+ * stands in for the body's run vocabulary: `run.set`, `run.wait`, `run.emit`.
+ */
+export type ActionHandler = (row: Row | undefined, args: Record<string, unknown>, run: MockRunControl) => unknown;
+export interface Fixtures {
+    tables?: Record<string, Row[]>;
+    /**
+     * Handlers by the action's wire name: `check_overdue` for the project
+     * action `check-overdue`, `issues.close_issue` for a row action. The YAML
+     * key with dashes works too; two keys naming the same action throw.
+     */
+    actions?: Record<string, ActionHandler>;
+    /** `when:` stand-ins: which row actions a record offers. */
+    available?: Record<string, (row: Row) => string[]>;
+    /** Reject writes: return a message (or field errors) to refuse. */
+    validate?: (table: string, row: Row) => string | Record<string, string> | void;
+    /**
+     * The protocol this server speaks (default 1). Like vantage-server, a
+     * `hello` naming another gets `error {code: "protocol"}` and a 1002 close.
+     */
+    protocol?: number;
+    /** Refuse every `hello` with this message. */
+    refuseHello?: string;
+    /**
+     * Start an action's handler before the invoking socket follows the run,
+     * as vantage-server does: what it sets and sends before its first `await`
+     * arrives inside the first snapshot. By default it starts just after.
+     */
+    eager?: boolean;
+    /** The features `welcome` offers (default: all this client knows); `[]` is a server without runs. */
+    features?: string[];
+}
+export declare class MockStore {
+    readonly schema: SchemaMeta;
+    protected readonly fixtures: Fixtures;
+    readonly tables: Map<string, Map<string, Row>>;
+    /** How many times a client connected. */
+    connects: number;
+    protected clients: Set<MockTransport>;
+    protected seq: number;
+    protected nextSub: number;
+    /** Every run, by id. */
+    readonly runs: Map<string, MockRun>;
+    protected subs: Map<number, {
+        spec: CollectionSpec;
+        client: MockTransport;
+        ids: string[];
+    }>;
+    constructor(schema: SchemaMeta, fixtures?: Fixtures);
+    private readonly handlers;
+    /** Change a record as if someone else did. */
+    upsert(table: string, row: Row): void;
+    remove(table: string, id: string): void;
+    /** A coarse change: clients re-read every collection on `table`. */
+    invalidate(table: string): void;
+    /** Replace a table's rows without telling anyone, as a reload might. */
+    setRows(table: string, rows: Row[]): void;
+    protected broadcast(events: ChangeEvent[], table: string): void;
+    protected table(name: string): Map<string, Row>;
+    protected available(table: string, row: Row): string[];
+    protected wire(table: string, row: Row): WireRecord;
+    protected records(table: string, ids: string[]): WireRecord[];
+    protected query(spec: CollectionSpec): string[];
+    /** Start or attach to a run (see ./mock-runs). */
+    protected invoke(client: MockTransport, id: number, frame: Extract<ClientFrame, {
+        t: "invoke";
+    }>): void;
+    private execute;
+    /** Apply one write, checked by the fixtures' `validate`. */
+    protected flash(id: number, item: FlashItem): ServerFrame;
+}

package/dist/mock-store.js

@@ -0,0 +1,158 @@
+// The MockServer's data side: its tables, the connected clients and their
+// collections, the writes and actions that change the tables, and the
+// `changed`/`members` broadcasts a change causes.
+import { query } from "./mock-query.js";
+import { MockRun, invokeRun } from "./mock-runs.js";
+/**
+ * The fixture handlers keyed by wire name. vantage-server names an action
+ * on the wire with its key's dashes turned into underscores, so
+ * `check-overdue` and `check_overdue` are the same action.
+ */
+function handlersByWireName(actions) {
+    const handlers = new Map();
+    const keys = new Map();
+    for (const [key, handler] of Object.entries(actions)) {
+        const wire = key.replaceAll("-", "_");
+        const other = keys.get(wire);
+        if (other !== undefined)
+            throw new Error(`MockServer: actions \`${other}\` and \`${key}\` are the same action \`${wire}\``);
+        keys.set(wire, key);
+        handlers.set(wire, handler);
+    }
+    return handlers;
+}
+export class MockStore {
+    schema;
+    fixtures;
+    tables = new Map();
+    /** How many times a client connected. */
+    connects = 0;
+    clients = new Set();
+    seq = 0;
+    nextSub = 1;
+    /** Every run, by id. */
+    runs = new Map();
+    subs = new Map();
+    constructor(schema, fixtures = {}) {
+        this.schema = schema;
+        this.fixtures = fixtures;
+        for (const [table, rows] of Object.entries(fixtures.tables ?? {}))
+            this.setRows(table, rows);
+        this.handlers = handlersByWireName(fixtures.actions ?? {});
+    }
+    handlers;
+    /** Change a record as if someone else did. */
+    upsert(table, row) {
+        this.table(table).set(row.id, { ...this.table(table).get(row.id), ...row });
+        this.broadcast([{ k: "upsert", table, id: row.id, record: this.wire(table, this.table(table).get(row.id)) }], table);
+    }
+    remove(table, id) {
+        this.table(table).delete(id);
+        this.broadcast([{ k: "removed", table, id }], table);
+    }
+    /** A coarse change: clients re-read every collection on `table`. */
+    invalidate(table) {
+        this.broadcast([{ k: "invalidated", table }], table);
+    }
+    /** Replace a table's rows without telling anyone, as a reload might. */
+    setRows(table, rows) {
+        this.tables.set(table, new Map(rows.map((r) => [r.id, { ...r }])));
+    }
+    /** @internal */ attach(client) {
+        this.clients.add(client);
+        this.connects++;
+    }
+    /** @internal */ detach(client) {
+        this.clients.delete(client);
+        for (const [sub, s] of this.subs)
+            if (s.client === client)
+                this.subs.delete(sub);
+        for (const run of this.runs.values())
+            run.unfollow(client);
+    }
+    broadcast(events, table) {
+        this.seq++;
+        for (const client of this.clients)
+            client.deliver({ t: "changed", seq: this.seq, events });
+        for (const [sub, s] of this.subs) {
+            if (s.spec.table !== table)
+                continue;
+            const ids = this.query(s.spec).slice(0, s.spec.limit ?? 500);
+            if (ids.join() !== s.ids.join()) {
+                const fresh = ids.filter((i) => !s.ids.includes(i));
+                s.ids = ids;
+                s.client.deliver({ t: "members", sub, start: 0, ids, records: this.records(table, fresh), total: ids.length, complete: true });
+            }
+        }
+    }
+    table(name) {
+        let t = this.tables.get(name);
+        if (!t)
+            this.tables.set(name, (t = new Map()));
+        return t;
+    }
+    available(table, row) {
+        const fn = this.fixtures.available?.[table];
+        if (fn)
+            return fn(row);
+        return Object.entries(this.schema.tables[table]?.actions ?? {})
+            .filter(([, a]) => a.perRow)
+            .map(([n]) => n);
+    }
+    wire(table, row) {
+        return { ...row, $actions: this.available(table, row) };
+    }
+    records(table, ids) {
+        return ids.map((i) => this.wire(table, this.table(table).get(i)));
+    }
+    query(spec) {
+        return query(this.schema, [...this.table(spec.table).values()], spec);
+    }
+    /** Start or attach to a run (see ./mock-runs). */
+    invoke(client, id, frame) {
+        invokeRun(this.runs, client, id, frame, (frame) => {
+            const refuse = (code, message) => ({ t: "error", id, kind: code, code, message });
+            const handler = this.handlers.get(frame.action);
+            if (!handler)
+                return refuse("forbidden", `no action \`${frame.action}\``);
+            const [table, name] = frame.action.includes(".") ? frame.action.split(".") : [undefined, frame.action];
+            const row = table && frame.rid ? this.table(table).get(frame.rid) : undefined;
+            if (table && frame.rid && !row)
+                return refuse("forbidden", "no record");
+            if (row && table && !this.available(table, row).includes(name))
+                return refuse("conflict", "not available for this record");
+            const meta = (table ? this.schema.tables[table]?.actions[name] : this.schema.actions[name]) ?? {};
+            const run = new MockRun(frame.run, frame.action, frame.rid, frame.args ?? {}, meta);
+            if (this.fixtures.eager)
+                void this.execute(run, handler, table, row);
+            else
+                queueMicrotask(() => void this.execute(run, handler, table, row));
+            return run;
+        });
+    }
+    async execute(run, handler, table, row) {
+        try {
+            const out = await handler(row, run.args, run);
+            if (row && table && out && typeof out === "object")
+                this.upsert(table, { ...row, ...out, id: row.id });
+            run.end(run.cancelled ? "cancelled" : "done", out ?? null);
+        }
+        catch (e) {
+            run.end(run.cancelled ? "cancelled" : "failed", undefined, e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Apply one write, checked by the fixtures' `validate`. */
+    flash(id, item) {
+        const table = this.table(item.table);
+        const rid = item.rid ?? (String(item.patch.id ?? "").includes(":") ? String(item.patch.id) : `${item.table}:${item.patch.id ?? Math.random().toString(36).slice(2)}`);
+        if (item.rid && !table.has(rid))
+            return { t: "rejected", id, message: "no such record" };
+        const next = { ...table.get(rid), ...item.patch, id: rid };
+        const invalid = this.fixtures.validate?.(item.table, next);
+        if (invalid) {
+            return typeof invalid === "string" ? { t: "rejected", id, message: invalid } : { t: "rejected", id, message: "invalid", field_errors: invalid };
+        }
+        this.upsert(item.table, next);
+        return { t: "flashed", id, rid, seq: this.seq, record: this.wire(item.table, next) };
+    }
+}

package/dist/mock-transport.d.ts

@@ -0,0 +1,16 @@
+import type { ClientFrame } from "./protocol.js";
+import type { Transport, TransportHandlers } from "./transport.js";
+import type { MockServer } from "./testing.js";
+export declare class MockTransport implements Transport {
+    private server;
+    private handlers?;
+    ready: boolean;
+    constructor(server: MockServer);
+    connect(handlers: TransportHandlers): void;
+    send(frame: ClientFrame & {
+        id?: number;
+    }): void;
+    /** Simulate a dropped connection; the client reconnects unless `code` is a refusal (1008). */
+    drop(code?: number, reason?: string): void;
+    close(): void;
+}

package/dist/mock-transport.js

@@ -0,0 +1,38 @@
+// The in-memory link between a client and the MockServer. Frames are
+// copied through JSON and delivered on a microtask, like a socket would.
+export class MockTransport {
+    server;
+    handlers;
+    ready = false;
+    constructor(server) {
+        this.server = server;
+    }
+    connect(handlers) {
+        this.handlers = handlers;
+        this.server.attach(this);
+        queueMicrotask(() => {
+            this.ready = true;
+            handlers.open();
+        });
+    }
+    send(frame) {
+        const copy = JSON.parse(JSON.stringify(frame));
+        queueMicrotask(() => this.server.handle(this, copy));
+    }
+    /** @internal Frames sent while the connection is down are lost, as on a real socket. */
+    deliver(frame) {
+        if (!this.ready)
+            return;
+        const copy = JSON.parse(JSON.stringify(frame));
+        queueMicrotask(() => this.ready && this.handlers?.message(copy));
+    }
+    /** Simulate a dropped connection; the client reconnects unless `code` is a refusal (1008). */
+    drop(code, reason) {
+        this.ready = false;
+        this.server.detach(this);
+        this.handlers?.close(code, reason);
+    }
+    close() {
+        this.drop();
+    }
+}

package/dist/model.d.ts

@@ -0,0 +1,5 @@
+import type { Vantage } from "./client.js";
+import type { RecordCell } from "./store.js";
+import type { Model, TableMeta } from "./types.js";
+export type AnyModel = Model & Record<string, any>;
+export declare function buildModelClass(db: Vantage<any>, table: string, meta: TableMeta): new (cell: RecordCell) => AnyModel;

package/dist/model.js

@@ -0,0 +1,169 @@
+// Model classes: one generated class per table, with the table's columns,
+// references, has-many collections and row actions on its prototype, plus
+// the edit draft (Servo) a model's `edit()` returns.
+import { State } from "./signal.js";
+import { reservedClash } from "./reserved.js";
+import { Reference } from "./table.js";
+import { pascal, sameValue, toColumns } from "./util.js";
+export function buildModelClass(db, table, meta) {
+    const clash = reservedClash(table, [
+        ...Object.entries(meta.columns)
+            .filter(([name, info]) => name !== "id" && !info.hidden)
+            .map(([name]) => ({ kind: "column", name })),
+        ...[...Object.keys(meta.references), ...Object.keys(meta.hasMany)].map((name) => ({ kind: "reference", name })),
+        ...Object.entries(meta.actions)
+            .filter(([, action]) => action.perRow)
+            .map(([name]) => ({ kind: "action", name })),
+    ]);
+    if (clash)
+        throw new Error(`vantage: ${clash}`);
+    const refs = new WeakMap();
+    const memo = (cell, key, make) => {
+        let m = refs.get(cell);
+        if (!m)
+            refs.set(cell, (m = new Map()));
+        if (!m.has(key))
+            m.set(key, make());
+        return m.get(key);
+    };
+    class ModelImpl {
+        $cell;
+        constructor($cell) {
+            this.$cell = $cell;
+        }
+    }
+    const proto = ModelImpl.prototype;
+    const define = (name, get) => Object.defineProperty(proto, name, {
+        get,
+        set() {
+            throw new TypeError(`vantage: \`${table}.${name}\` is read-only — use .edit() and .$flash(), or .patch({ ${name}: … })`);
+        },
+        enumerable: true,
+    });
+    define("$table", () => table);
+    define("id", function () {
+        return this.$cell.id;
+    });
+    define("$status", function () {
+        return this.$cell.status.get();
+    });
+    define("$errors", function () {
+        return this.$cell.errors.get();
+    });
+    define("$actions", function () {
+        return this.$cell.get("$actions") ?? [];
+    });
+    define("$title", function () {
+        return meta.title ? String(this.$cell.get(meta.title) ?? this.$cell.id) : this.$cell.id;
+    });
+    const shadowed = new Set(Object.keys(meta.references));
+    for (const [column, info] of Object.entries(meta.columns)) {
+        if (column === "id" || info.hidden || shadowed.has(column))
+            continue;
+        define(column, function () {
+            return this.$cell.get(column);
+        });
+    }
+    for (const [name, ref] of Object.entries(meta.references)) {
+        define(name, function () {
+            const cell = this.$cell;
+            return memo(cell, `ref:${name}`, () => new Reference(db, ref.table, () => cell.get(ref.column) ?? null));
+        });
+    }
+    for (const [name, many] of Object.entries(meta.hasMany)) {
+        define(name, function () {
+            return db.collection({ table: many.table, via: { table, id: this.$cell.id, ref: name } });
+        });
+    }
+    const rowActions = Object.entries(meta.actions).filter(([, action]) => action.perRow);
+    for (const [name] of rowActions) {
+        // A run awaited to its end; `$run.<name>` gives the run itself.
+        proto[name] = function (input, opts) {
+            return db.invoke(`${table}.${name}`, this.$cell.id, input ?? {}, opts);
+        };
+    }
+    define("$run", function () {
+        const id = this.$cell.id;
+        return memo(this.$cell, "$run", () => Object.fromEntries(rowActions.map(([name]) => [name, db.runs(`${table}.${name}`, id)])));
+    });
+    proto.edit = function () {
+        return createServo(db, this, meta);
+    };
+    proto.patch = function (fields) {
+        return db.write(table, this.id, toColumns(meta, fields));
+    };
+    proto.delete = function () {
+        return db.remove(table, this.id);
+    };
+    proto.hydrate = async function (keys) {
+        const wanted = keys ?? [...Object.keys(meta.references), ...Object.keys(meta.hasMany)];
+        await Promise.all(wanted.map((k) => this[k]?.load?.()));
+        return this;
+    };
+    Object.defineProperty(ModelImpl, "name", { value: pascal(table) });
+    return ModelImpl;
+}
+function createServo(db, model, meta) {
+    const cell = model.$cell;
+    const setpoints = new Map();
+    const version = new State(0);
+    const status = new State("tracking");
+    const column = (name) => meta.references[name]?.column ?? name;
+    const dirty = (name) => setpoints.has(name) && !sameValue(setpoints.get(name).peek(), cell.field(column(name)).peek());
+    const api = {
+        $model: model,
+        $dirty(name) {
+            version.get();
+            return dirty(name);
+        },
+        $revert(name) {
+            if (name)
+                setpoints.delete(name);
+            else
+                setpoints.clear();
+            version.set(version.peek() + 1);
+        },
+        async $flash() {
+            const changed = [...setpoints.keys()].filter(dirty);
+            if (changed.length === 0)
+                return { ok: true, value: model };
+            status.set("pending");
+            const result = await db.write(model.$table, cell.id, Object.fromEntries(changed.map((k) => [column(k), setpoints.get(k).peek()])));
+            if (result.ok) {
+                for (const k of changed)
+                    setpoints.delete(k);
+                status.set("tracking");
+            }
+            else
+                status.set("failed");
+            version.set(version.peek() + 1);
+            return result;
+        },
+    };
+    return new Proxy(api, {
+        get(target, prop) {
+            if (prop === "$isDirty") {
+                version.get();
+                return [...setpoints.keys()].some(dirty);
+            }
+            if (prop === "$status")
+                return status.get();
+            if (prop === "$errors")
+                return cell.errors.get();
+            if (prop in target)
+                return target[prop];
+            version.get();
+            const setpoint = setpoints.get(prop);
+            return setpoint ? setpoint.get() : cell.get(column(prop));
+        },
+        set(_, prop, value) {
+            let state = setpoints.get(prop);
+            if (!state)
+                setpoints.set(prop, (state = new State(value)));
+            else
+                state.set(value);
+            version.set(version.peek() + 1);
+            return true;
+        },
+    });
+}

package/dist/persist.d.ts

@@ -0,0 +1,47 @@
+import type { Cursor, FlashItem, WireRecord } from "./protocol.js";
+export interface Persisted {
+    records: {
+        table: string;
+        record: WireRecord;
+    }[];
+    cursor: Cursor | null;
+    outbox: FlashItem[];
+}
+export interface PersistChange {
+    /** `record: null` removes it. */
+    records?: {
+        table: string;
+        id: string;
+        record: WireRecord | null;
+    }[];
+    cursor?: Cursor;
+    outbox?: FlashItem[];
+}
+export interface Storage {
+    load(): Promise<Persisted>;
+    save(change: PersistChange): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Keeps everything in memory (tests; SSR). */
+export declare class MemoryStorage implements Storage {
+    private records;
+    private cursor;
+    private outbox;
+    load(): Promise<Persisted>;
+    save(change: PersistChange): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * IndexedDB, one database per server + schema. A schema change starts a
+ * fresh database (`name` includes the hash), so stale shapes never load.
+ */
+export declare class IndexedDBStorage implements Storage {
+    private readonly name;
+    private readonly schemaHash;
+    private db?;
+    constructor(name: string, schemaHash: string);
+    private open;
+    load(): Promise<Persisted>;
+    save(change: PersistChange): Promise<void>;
+    clear(): Promise<void>;
+}

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);
+    });
+}