@vantage-ui/client 0.0.0-stage → 0.4.4

package/dist/collection-cell.d.ts

@@ -0,0 +1,69 @@
+import type { CollectionSpec } from "./protocol.js";
+import { State } from "./signal.js";
+import type { LoadState, Model } from "./types.js";
+import type { Vantage } from "./client.js";
+type AnyModel = Model & Record<string, any>;
+/** A window's cell spec: the collection's, with the window's size as its limit. */
+export type CellSpec = CollectionSpec & {
+    $window?: boolean;
+};
+/** One key per description, whatever order its parts were set in. */
+export declare function specKey({ table, where, search, sort, via, limit, $window }: CellSpec): string;
+/** Shared state behind every Collection with the same description. Not exported from the package. */
+export declare class CollectionCell {
+    private db;
+    readonly spec: CellSpec;
+    readonly key: string;
+    readonly ids: State<string[]>;
+    readonly loadState: State<LoadState>;
+    readonly total: State<number | null>;
+    readonly error: State<string | null>;
+    sub: number | null;
+    start: number;
+    pinned: boolean;
+    /** The server refused to open it; reads don't retry until a resync. */
+    refused: boolean;
+    touched: number;
+    wantedWindow?: {
+        start: number;
+        count: number;
+    };
+    private opening?;
+    private settled?;
+    private firstLoad;
+    private modelsCache?;
+    private windowWaiters;
+    constructor(db: Vantage<any>, spec: CellSpec, key: string);
+    /** Something read us: open if closed. After a final refusal of the connection, settle with its message. */
+    read(): void;
+    /** Open on the server, unless an open is already on its way. The ids shown so far stay until the reply. */
+    open(): Promise<void>;
+    /**
+     * 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(): void;
+    /** Scrolled away from the start: the first reply's ids aren't the ones on screen. */
+    get scrolled(): boolean;
+    wanted(): boolean;
+    opened(sub: number): void;
+    loaded(sub: number, start: number, ids: string[], total: number | null, complete: boolean): void;
+    members(start: number, ids: string[], total: number | null, complete: boolean): void;
+    failed(message: string): void;
+    /** Resolves once rows `start..start+count` have arrived, or the cell failed (refused, or the connection halted). */
+    whenWindow(start: number, count: number): Promise<void>;
+    /** Whether a `whenLoaded()` is still waiting for its rows. */
+    get waitingForWindow(): boolean;
+    /**
+     * 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: number, count: number): boolean;
+    /** Resolve every `whenWindow()` whose rows are now here. */
+    private wakeWindows;
+    drop(id: string): void;
+    whenLoaded(): Promise<void>;
+    models(): AnyModel[];
+}
+export {};

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