@vantage-ui/client 0.0.0-stage → 0.4.3

package/dist/collection-cell.js

@@ -0,0 +1,153 @@
+// The shared cell behind every Collection with the same description: the
+// server's ordered ids for it, its load state, the sub that keeps it live,
+// and the `window().whenLoaded()` promises waiting on its rows.
+import { State } from "./signal.js";
+/** One key per description, whatever order its parts were set in. */
+export function specKey({ table, where, search, sort, via, limit, $window }) {
+    return JSON.stringify({ table, where: where?.length ? where : undefined, search: search || undefined, sort, via, limit, $window });
+}
+/** Shared state behind every Collection with the same description. Not exported from the package. */
+export class CollectionCell {
+    db;
+    spec;
+    key;
+    ids;
+    loadState = new State("idle");
+    total = new State(null);
+    error = new State(null);
+    sub = null;
+    start = 0;
+    pinned = false;
+    /** The server refused to open it; reads don't retry until a resync. */
+    refused = false;
+    touched = Date.now();
+    wantedWindow;
+    opening;
+    settled;
+    firstLoad;
+    modelsCache;
+    windowWaiters = [];
+    constructor(db, spec, key) {
+        this.db = db;
+        this.spec = spec;
+        this.key = key;
+        this.ids = new State([], { observed: () => this.read() });
+        this.firstLoad = new Promise((resolve) => (this.settled = resolve));
+    }
+    /** Something read us: open if closed. After a final refusal of the connection, settle with its message. */
+    read() {
+        this.touched = Date.now();
+        if (this.sub !== null || this.refused)
+            return;
+        const halted = this.db.haltedWith;
+        if (halted !== undefined)
+            return this.failed(halted);
+        if (this.db.connection.peek().status === "open") {
+            if (this.loadState.peek() === "idle")
+                this.loadState.set("loading");
+            void this.open();
+        }
+    }
+    /** Open on the server, unless an open is already on its way. The ids shown so far stay until the reply. */
+    open() {
+        if (!this.opening) {
+            const opening = this.db.openCollection(this).finally(() => {
+                if (this.opening === opening)
+                    this.opening = undefined;
+            });
+            this.opening = opening;
+        }
+        return this.opening;
+    }
+    /**
+     * The server dropped every sub (a resync): forget the open in flight, so
+     * the next one goes out, and a refusal, so `whenLoaded()` waits for the reopen.
+     */
+    reset() {
+        this.sub = null;
+        this.opening = undefined;
+        if (!this.refused)
+            return;
+        this.refused = false;
+        this.error.set(null);
+        this.loadState.set("loading");
+    }
+    /** Scrolled away from the start: the first reply's ids aren't the ones on screen. */
+    get scrolled() {
+        return !!this.wantedWindow && this.wantedWindow.start !== 0;
+    }
+    wanted() {
+        return this.ids.observed || this.loadState.observed || Date.now() - this.touched < this.db.keepAliveMs;
+    }
+    opened(sub) {
+        this.sub = sub;
+        this.refused = false;
+        this.error.set(null);
+    }
+    loaded(sub, start, ids, total, complete) {
+        this.opened(sub);
+        this.members(start, ids, total, complete);
+    }
+    members(start, ids, total, complete) {
+        this.start = start;
+        this.ids.set(ids);
+        this.total.set(total);
+        this.loadState.set(complete ? "complete" : "partial");
+        this.settled?.();
+        this.wakeWindows();
+    }
+    failed(message) {
+        this.refused = true;
+        this.error.set(message);
+        this.loadState.set("error");
+        this.settled?.();
+        this.wakeWindows();
+    }
+    /** Resolves once rows `start..start+count` have arrived, or the cell failed (refused, or the connection halted). */
+    whenWindow(start, count) {
+        this.read();
+        if (this.windowSettled(start, count))
+            return Promise.resolve();
+        return new Promise((resolve) => this.windowWaiters.push({ start, count, resolve }));
+    }
+    /** Whether a `whenLoaded()` is still waiting for its rows. */
+    get waitingForWindow() {
+        return this.windowWaiters.length > 0;
+    }
+    /**
+     * Failed, or the rows from `start` arrived: `count` of them, or fewer when
+     * the frame said `complete`. An estimated `total` never ends the window
+     * early. Reads state without tracking it.
+     */
+    windowSettled(start, count) {
+        const state = this.loadState.peek();
+        if (state === "error")
+            return true;
+        if ((state !== "complete" && state !== "partial") || this.start !== start)
+            return false;
+        return state === "complete" || this.ids.peek().length >= count;
+    }
+    /** Resolve every `whenWindow()` whose rows are now here. */
+    wakeWindows() {
+        const waiting = this.windowWaiters;
+        this.windowWaiters = waiting.filter((w) => !this.windowSettled(w.start, w.count));
+        for (const w of waiting)
+            if (this.windowSettled(w.start, w.count))
+                w.resolve();
+    }
+    drop(id) {
+        const ids = this.ids.peek();
+        if (ids.includes(id))
+            this.ids.set(ids.filter((x) => x !== id));
+    }
+    whenLoaded() {
+        this.read();
+        return this.firstLoad;
+    }
+    models() {
+        const ids = this.ids.get();
+        if (this.modelsCache?.ids !== ids)
+            this.modelsCache = { ids, models: ids.map((id) => this.db.model(this.spec.table, id)) };
+        return this.modelsCache.models;
+    }
+}

package/dist/collection.d.ts

@@ -0,0 +1,32 @@
+import type { CollectionSpec, Where } from "./protocol.js";
+import type { CollectionWindow, LazyCollection, LoadState, Model } from "./types.js";
+import type { Vantage } from "./client.js";
+type AnyModel = Model & Record<string, any>;
+export declare class Collection implements LazyCollection<AnyModel> {
+    private db;
+    readonly spec: CollectionSpec;
+    /** When it was made; a new one is kept for a while before anything reads it. */
+    readonly created: number;
+    private cells;
+    constructor(db: Vantage<any>, spec: CollectionSpec);
+    /** The keys of the cells it has read (its own, and its windows'). */
+    cellKeys(): string[];
+    private cellFor;
+    private get cell();
+    get elements(): readonly AnyModel[];
+    get length(): number;
+    get loadState(): LoadState;
+    get total(): number | null;
+    get totalExact(): boolean;
+    get error(): string | null;
+    map<U>(fn: (item: AnyModel, index: number) => U): U[];
+    forEach(fn: (item: AnyModel, index: number) => void): void;
+    [Symbol.iterator](): ArrayIterator<AnyModel>;
+    where(conditions: Partial<Record<string, unknown>> | Where[]): LazyCollection<AnyModel>;
+    sort(column: string, direction?: "asc" | "desc"): LazyCollection<AnyModel>;
+    search(text: string): LazyCollection<AnyModel>;
+    limit(rows: number): LazyCollection<AnyModel>;
+    window(start: number, count: number): CollectionWindow<AnyModel>;
+    load(): Promise<LazyCollection<AnyModel>>;
+}
+export {};

package/dist/collection.js

@@ -0,0 +1,122 @@
+// Collections: a description (table, where, sort, search, via, window) read
+// through the shared CollectionCell that holds the server's ids for it.
+// `db.collection(spec)` keeps one Collection per description.
+export class Collection {
+    db;
+    spec;
+    /** When it was made; a new one is kept for a while before anything reads it. */
+    created = Date.now();
+    cells = new Set();
+    constructor(db, spec) {
+        this.db = db;
+        this.spec = spec;
+    }
+    /** The keys of the cells it has read (its own, and its windows'). */
+    cellKeys() {
+        return [...this.cells];
+    }
+    cellFor(spec) {
+        const cell = this.db.collectionCell(spec);
+        this.cells.add(cell.key);
+        return cell;
+    }
+    get cell() {
+        const cell = this.cellFor(this.spec);
+        cell.read();
+        return cell;
+    }
+    get elements() {
+        return this.cell.models();
+    }
+    get length() {
+        const cell = this.cell;
+        const ids = cell.ids.get();
+        return cell.loadState.get() === "complete" ? ids.length : (cell.total.get() ?? ids.length);
+    }
+    get loadState() {
+        return this.cell.loadState.get();
+    }
+    get total() {
+        return this.cell.total.get();
+    }
+    get totalExact() {
+        const cell = this.cell;
+        return cell.loadState.get() === "complete" && cell.total.get() !== null;
+    }
+    get error() {
+        return this.cell.error.get();
+    }
+    map(fn) {
+        return this.elements.map(fn);
+    }
+    forEach(fn) {
+        this.elements.forEach(fn);
+    }
+    [Symbol.iterator]() {
+        return this.elements[Symbol.iterator]();
+    }
+    where(conditions) {
+        const meta = this.db.meta(this.spec.table);
+        const added = Array.isArray(conditions)
+            ? conditions
+            : Object.entries(conditions).map(([k, v]) => {
+                const column = meta.references[k]?.column ?? k;
+                if (Array.isArray(v))
+                    return [column, "in", v];
+                if (v && typeof v === "object" && !Array.isArray(v)) {
+                    const [op, operand] = Object.entries(v)[0];
+                    return [column, op, operand];
+                }
+                return [column, "eq", v];
+            });
+        return this.db.collection({ ...this.spec, where: [...(this.spec.where ?? []), ...added] });
+    }
+    sort(column, direction = "asc") {
+        return this.db.collection({ ...this.spec, sort: [column, direction] });
+    }
+    search(text) {
+        return this.db.collection({ ...this.spec, search: text || undefined });
+    }
+    limit(rows) {
+        return this.db.collection({ ...this.spec, limit: rows });
+    }
+    window(start, count) {
+        const cell = this.cellFor({ ...this.spec, limit: count, $window: true });
+        const moved = !cell.wantedWindow || cell.wantedWindow.start !== start || cell.wantedWindow.count !== count;
+        cell.wantedWindow = { start, count };
+        cell.read();
+        if (moved && cell.sub !== null)
+            this.db.moveWindow(cell);
+        const ids = cell.ids.get();
+        const loadState = cell.loadState.get();
+        const total = cell.total.get();
+        const error = cell.error.get();
+        const items = Array.from({ length: count }, (_, i) => {
+            const at = start + i - cell.start;
+            const id = at >= 0 && at < ids.length ? ids[at] : undefined;
+            return id ? this.db.model(this.spec.table, id) : undefined;
+        });
+        const gap = items.indexOf(undefined);
+        const end = start + (gap === -1 ? count : gap); // rows arrived from `start` without a gap
+        const settled = cell.windowSettled(start, count);
+        // The last `rows`/`members` frame said `complete`: the server sent every row.
+        const totalExact = loadState === "complete" && total !== null;
+        return {
+            start,
+            count,
+            items,
+            at: (index) => items[index - start],
+            error,
+            total,
+            totalExact,
+            settled,
+            length: total ?? end,
+            lengthExact: total !== null ? totalExact : settled && error === null && (loadState === "complete" || end < start + count),
+            whenLoaded: () => cell.whenWindow(start, count).then(() => this.window(start, count)),
+        };
+    }
+    async load() {
+        await this.cellFor(this.spec).whenLoaded();
+        return this;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createVantage } from "./client.js";
+export type { Vantage, VantageDb, VantageOptions, TableHandle, Tables, ProjectActions } from "./client.js";
+export { State, batch, autorun } from "./signal.js";
+export type { Transport } from "./transport.js";
+export { MemoryStorage, IndexedDBStorage, type Storage } from "./persist.js";
+export type { ActionError, ActionResult, CollectionWindow, Connection, ConnectionStatus, FieldMeta, Hydrated, LazyCollection, LazyReference, LoadState, Model, Presence, RelationKeys, RowStatus, SchemaMeta, SchemaTypes, Servo, TableMeta, WritableFields, } from "./types.js";
+export type { CollectionSpec, Where, Sort, WireRecord, Json, RunCode } from "./protocol.js";
+export type { Run, RunError, RunFactory, RunMessageOf, RunStatus, RunTypes, StartOptions } from "./run/types.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+// @vantage-ui/client — a vantage-ui project as a typed, live object graph.
+//
+//   import { createVantage } from "@vantage-ui/client";
+//   import { schema, type Schema } from "./vantage.gen";
+//
+//   const db = createVantage<Schema>({ schema, token }); // ws(s)://<page host>/v1/ws
+//   db.order.sort("created_at", "desc").map((o) => o.client.value?.name);
+//   await order.cancel_order({ reason: "out_of_stock" });
+//   const run = db.run.restock.start({ bakery }); // run.state, run.on(…), await run.done
+//
+// React bindings: "@vantage-ui/client/react". Tests: "@vantage-ui/client/testing".
+export { createVantage } from "./client.js";
+export { State, batch, autorun } from "./signal.js";
+export { MemoryStorage, IndexedDBStorage } from "./persist.js";

package/dist/mock-query.d.ts

@@ -0,0 +1,9 @@
+import type { CollectionSpec } from "./protocol.js";
+import type { SchemaMeta } from "./types.js";
+export type Row = Record<string, unknown> & {
+    id: string;
+};
+/** The ids of `rows` that `spec` selects, in its order. */
+export declare function query(schema: SchemaMeta, rows: Row[], spec: CollectionSpec): string[];
+/** A minimal schema for one table whose columns are the keys of `rows`. */
+export declare function tableSchema(table: string, rows: Row[]): SchemaMeta;

package/dist/mock-query.js

@@ -0,0 +1,75 @@
+// How the MockServer answers a collection: filter, traverse, search and
+// sort like vantage-server does.
+/** The ids of `rows` that `spec` selects, in its order. */
+export function query(schema, rows, spec) {
+    for (const w of spec.where ?? [])
+        rows = rows.filter((r) => matches(r[w[0]], w));
+    if (spec.via) {
+        const fk = schema.tables[spec.via.table]?.hasMany[spec.via.ref]?.foreignKey;
+        rows = rows.filter((r) => fk && r[fk] === spec.via.id);
+    }
+    if (spec.search) {
+        const q = spec.search.toLowerCase();
+        rows = rows.filter((r) => Object.values(r).some((v) => String(v ?? "").toLowerCase().includes(q)));
+    }
+    if (spec.sort) {
+        const [col, dir] = spec.sort;
+        rows = [...rows].sort((a, b) => (dir === "desc" ? -1 : 1) * compare(a[col], b[col]));
+    }
+    return rows.map((r) => r.id);
+}
+function matches(value, [, op, operand]) {
+    switch (op) {
+        case "eq":
+            return value === operand;
+        case "ne":
+            return value !== operand;
+        case "gt":
+            return compare(value, operand) > 0;
+        case "gte":
+            return compare(value, operand) >= 0;
+        case "lt":
+            return compare(value, operand) < 0;
+        case "lte":
+            return compare(value, operand) <= 0;
+        case "in":
+            return Array.isArray(operand) && operand.includes(value);
+        case "not_in":
+            return Array.isArray(operand) && !operand.includes(value);
+        case "like":
+            return String(value ?? "").toLowerCase().includes(String(operand).toLowerCase());
+    }
+}
+function compare(a, b) {
+    if (a == null)
+        return b == null ? 0 : 1;
+    if (b == null)
+        return -1;
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    return String(a).localeCompare(String(b));
+}
+/** A minimal schema for one table whose columns are the keys of `rows`. */
+export function tableSchema(table, rows) {
+    const columns = Object.fromEntries([...new Set(["id", ...rows.flatMap((r) => Object.keys(r))])].map((c) => [c, { type: "string" }]));
+    return {
+        hash: "mock",
+        tables: {
+            [table]: {
+                key: table,
+                load: "lazy",
+                persist: false,
+                live: "push",
+                readOnly: false,
+                idColumn: "id",
+                title: null,
+                collectionLimit: 500,
+                columns,
+                references: {},
+                hasMany: {},
+                actions: {},
+            },
+        },
+        actions: {},
+    };
+}

package/dist/mock-runs.d.ts

@@ -0,0 +1,61 @@
+import type { MockTransport } from "./mock-transport.js";
+import type { ClientFrame, Json, ServerFrame } from "./protocol.js";
+import type { RunMeta } from "./schema-meta.js";
+/** What a handler's run can do, like a body's run vocabulary. */
+export interface MockRunControl {
+    readonly id: string;
+    get(name: string): unknown;
+    /** `state.<name> = value`: a patch to every follower. */
+    set(name: string, value: unknown): void;
+    /** Several variables in one patch, as the server's throttle coalesces them. */
+    update(values: Record<string, unknown>): void;
+    emit(name: string, payload?: unknown): void;
+    /** `notify(text)`: the `vantage.notify` message. */
+    notify(text: string): void;
+    /** Resolves once `state.<name>` is truthy; rejects when the run is cancelled. */
+    wait(name: string): Promise<unknown>;
+    readonly cancelled: boolean;
+}
+type Status = "running" | "done" | "failed" | "cancelled";
+type Invoke = Extract<ClientFrame, {
+    t: "invoke";
+}>;
+export declare class MockRun implements MockRunControl {
+    readonly id: string;
+    readonly action: string;
+    readonly rid: string | undefined;
+    readonly args: Record<string, unknown>;
+    readonly meta: RunMeta;
+    status: Status;
+    result: unknown;
+    error: string | undefined;
+    readonly state: Record<string, unknown>;
+    readonly messages: {
+        name: string;
+        payload: Json;
+        seq: number;
+    }[];
+    private seq;
+    private followers;
+    private waiters;
+    constructor(id: string, action: string, rid: string | undefined, args: Record<string, unknown>, meta: RunMeta);
+    get cancelled(): boolean;
+    get finished(): boolean;
+    get(name: string): unknown;
+    set(name: string, value: unknown): void;
+    update(values: Record<string, unknown>): void;
+    emit(name: string, payload?: unknown): void;
+    notify(text: string): void;
+    wait(name: string): Promise<unknown>;
+    private outcome;
+    private send;
+}
+/** The answer to `invoke`, as vantage-server gives it. `start` runs a new run's handler. */
+export declare function invokeRun(runs: Map<string, MockRun>, client: MockTransport, id: number, frame: Invoke, start: (frame: Invoke & {
+    action: string;
+}) => MockRun | ServerFrame): void;
+/** `run_set`: inputs only, of their type. */
+export declare function setInput(run: MockRun | undefined, id: number, frame: Extract<ClientFrame, {
+    t: "run_set";
+}>): ServerFrame;
+export {};

package/dist/mock-runs.js

@@ -0,0 +1,165 @@
+// The MockServer's action runs: `invoke` starts or attaches, the handler
+// runs with a control object standing in for a Rhai body (`state`, `wait`,
+// `emit`, `notify`), and every follower gets `run` frames as vantage-server
+// sends them: a snapshot first, then one change per frame.
+export class MockRun {
+    id;
+    action;
+    rid;
+    args;
+    meta;
+    status = "running";
+    result = undefined;
+    error;
+    state = {};
+    messages = [];
+    seq = 0;
+    followers = new Set();
+    waiters = [];
+    constructor(id, action, rid, args, meta) {
+        this.id = id;
+        this.action = action;
+        this.rid = rid;
+        this.args = args;
+        this.meta = meta;
+        for (const [name, info] of Object.entries(meta.state ?? {}))
+            this.state[name] = info.default;
+    }
+    get cancelled() {
+        return this.status === "cancelled";
+    }
+    get finished() {
+        return this.status !== "running";
+    }
+    get(name) {
+        return this.state[name];
+    }
+    set(name, value) {
+        this.update({ [name]: value });
+    }
+    update(values) {
+        if (this.finished)
+            throw new Error(this.cancelled ? "cancelled" : "the run has finished");
+        Object.assign(this.state, values);
+        this.send({ state: values });
+        for (const w of this.waiters.filter((w) => values[w.name])) {
+            this.waiters.splice(this.waiters.indexOf(w), 1);
+            w.resolve(values[w.name]);
+        }
+    }
+    emit(name, payload = null) {
+        if (this.finished)
+            throw new Error("the run has finished");
+        // `send` gives the frame the next seq; the message keeps it, as the server's does.
+        const message = { name, payload: payload, seq: this.seq + 1 };
+        this.messages.push(message);
+        if (this.messages.length > 100)
+            this.messages.shift();
+        this.send({ messages: [message] });
+    }
+    notify(text) {
+        this.emit("vantage.notify", { text });
+    }
+    wait(name) {
+        if (this.cancelled)
+            return Promise.reject(new Error("cancelled"));
+        if (this.state[name])
+            return Promise.resolve(this.state[name]);
+        return new Promise((resolve, reject) => this.waiters.push({ name, resolve, reject }));
+    }
+    /** @internal Follow on `client`: the snapshot now, changes after. */
+    follow(client) {
+        this.followers.add(client);
+        client.deliver({ t: "run", ...this.snapshot() });
+    }
+    /** @internal */ unfollow(client) {
+        this.followers.delete(client);
+    }
+    /** @internal The snapshot for a client that only reads the outcome. */
+    snapshot() {
+        return { run: this.id, seq: this.seq, status: "running", state: { ...this.state }, messages: [...this.messages], ...this.outcome() };
+    }
+    /** @internal */ cancel() {
+        if (this.finished)
+            return;
+        this.end("cancelled");
+        for (const w of this.waiters.splice(0))
+            w.reject(new Error("cancelled"));
+    }
+    /** @internal */ end(status, result, error) {
+        if (this.finished)
+            return;
+        this.status = status;
+        this.result = result;
+        this.error = error;
+        this.send(this.outcome());
+    }
+    outcome() {
+        if (this.status === "done")
+            return { status: "done", result: (this.result ?? null) };
+        if (this.status === "failed")
+            return { status: "failed", error: { code: "failed", message: this.error ?? "failed" } };
+        if (this.status === "cancelled")
+            return { status: "cancelled" };
+        return {};
+    }
+    send(change) {
+        this.seq++;
+        for (const client of this.followers)
+            client.deliver({ t: "run", run: this.id, seq: this.seq, ...change });
+    }
+}
+/** The answer to `invoke`, as vantage-server gives it. `start` runs a new run's handler. */
+export function invokeRun(runs, client, id, frame, start) {
+    const reply = (f) => client.deliver(f);
+    const existing = runs.get(frame.run);
+    if (!frame.action || existing) {
+        if (!existing)
+            return reply({ t: "error", id, kind: "forbidden", code: "forbidden", message: `no run \`${frame.run}\`` });
+        const same = !frame.action || (existing.action === frame.action && existing.rid === frame.rid && JSON.stringify(existing.args) === JSON.stringify(frame.args ?? {}));
+        if (!same)
+            return reply({ t: "error", id, kind: "conflict", code: "conflict", message: `run \`${frame.run}\` was started with another action, record or args` });
+        reply({ t: "result", id, run: frame.run, status: existing.finished ? "done" : "attached" });
+        if (existing.finished)
+            return client.deliver({ t: "run", ...existing.snapshot() });
+        return existing.follow(client);
+    }
+    const started = start(frame);
+    if (!(started instanceof MockRun))
+        return reply({ ...started, id });
+    runs.set(frame.run, started);
+    reply({ t: "result", id, run: frame.run, status: "started" });
+    started.follow(client);
+}
+/** `run_set`: inputs only, of their type. */
+export function setInput(run, id, frame) {
+    if (!run)
+        return { t: "error", id, kind: "forbidden", code: "forbidden", message: `no run \`${frame.run}\`` };
+    if (run.finished)
+        return { t: "error", id, kind: "conflict", code: "conflict", message: "the run has finished" };
+    const info = run.meta.state?.[frame.name];
+    if (!info?.input)
+        return { t: "error", id, kind: "invalid", code: "invalid", message: `\`state.${frame.name}\` is not an input` };
+    if (!fits(info.type, frame.value))
+        return { t: "error", id, kind: "invalid", code: "invalid", message: `\`state.${frame.name}\` takes a ${info.type}` };
+    run.set(frame.name, frame.value);
+    return { t: "ack", id };
+}
+function fits(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "int":
+            return Number.isInteger(value);
+        case "float":
+            return typeof value === "number";
+        case "bool":
+            return typeof value === "boolean";
+        case "list":
+            return Array.isArray(value);
+        case "map":
+            return value !== null && typeof value === "object" && !Array.isArray(value);
+        default:
+            return true;
+    }
+}