@vantage-ui/client 0.0.0-stage → 0.4.4

package/dist/client-core.js

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

package/dist/client-loading.d.ts

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

package/dist/client-loading.js

@@ -0,0 +1,229 @@
+// Reading: records by id (batched per microtask), collections and their
+// windows, and the sweep that closes what nothing has shown for a while.
+import { ClientCore } from "./client-core.js";
+import { CollectionCell, specKey } from "./collection-cell.js";
+import { batch } from "./signal.js";
+export class ClientLoading extends ClientCore {
+    /**
+     * @internal Load records by id, batched per microtask. A record the server refused
+     * isn't asked for again, and after a final refusal of the connection
+     * every record resolves at once, refused with its message.
+     */
+    requestRecords(table, ids) {
+        const halted = this.haltedWith;
+        const waits = ids.map((id) => {
+            const cell = this.store.cell(table, id);
+            const presence = cell.presence.peek();
+            if (presence === "loaded" || presence === "missing" || presence === "error")
+                return Promise.resolve();
+            if (halted !== undefined) {
+                cell.refused(halted);
+                return Promise.resolve();
+            }
+            if (presence !== "loading") {
+                cell.presence.set("loading");
+                let queued = this.loadQueue.get(table);
+                if (!queued)
+                    this.loadQueue.set(table, (queued = new Set()));
+                queued.add(id);
+                if (this.loadQueue.size === 1 && queued.size === 1)
+                    queueMicrotask(() => this.flushLoads());
+            }
+            return new Promise((resolve) => {
+                const key = `${table}\u0000${id}`;
+                this.loadWaiters.set(key, [...(this.loadWaiters.get(key) ?? []), resolve]);
+            });
+        });
+        return Promise.all(waits).then(() => undefined);
+    }
+    async flushLoads() {
+        if (!this.online)
+            return; // retried on reconnect
+        const queued = [...this.loadQueue];
+        this.loadQueue.clear();
+        await Promise.all(queued.map(async ([table, ids]) => {
+            const reply = await this.request({ t: "open_records", table, ids: [...ids] });
+            batch(() => {
+                if (reply.t === "records") {
+                    for (const r of reply.records)
+                        this.store.cell(table, r.id).applyServer(r);
+                    for (const id of reply.missing)
+                        this.store.cell(table, id).presence.set("missing");
+                }
+                else if (reply.t === "error" && reply.kind === "offline" && this.haltedWith === undefined) {
+                    for (const id of ids)
+                        this.store.cell(table, id).presence.set("none");
+                }
+                else if (reply.t === "error" && reply.kind === "offline") {
+                    for (const id of ids)
+                        this.store.cell(table, id).refused(this.haltedWith);
+                }
+                else {
+                    const message = reply.t === "error" ? reply.message : `unexpected reply \`${reply.t}\``;
+                    for (const id of ids)
+                        this.store.cell(table, id).refused(message);
+                }
+            });
+            for (const id of ids)
+                this.wake(table, id);
+        }));
+    }
+    wake(table, id) {
+        const key = `${table}\u0000${id}`;
+        for (const resolve of this.loadWaiters.get(key) ?? [])
+            resolve();
+        this.loadWaiters.delete(key);
+    }
+    /**
+     * @internal Fetch loaded records again; they stay readable until the reply
+     * replaces them. When the reload fails, the next read of each tries again.
+     */
+    async reloadRecords(table, ids) {
+        const reply = await this.request({ t: "open_records", table, ids });
+        if (reply.t !== "records") {
+            for (const id of ids) {
+                const cell = this.store.peek(table, id);
+                if (cell?.presence.peek() === "loaded")
+                    cell.reload = true;
+            }
+            return;
+        }
+        batch(() => {
+            for (const r of reply.records) {
+                const cell = this.store.cell(table, r.id);
+                cell.applyServer(r);
+                this.persistLater(cell);
+            }
+            for (const id of reply.missing)
+                this.store.cell(table, id).markRemoved();
+        });
+    }
+    // ------------------------------------------------------------ collections
+    /** @internal */ collectionCell(spec) {
+        const key = specKey(spec);
+        let cell = this.collections.get(key);
+        if (!cell) {
+            cell = new CollectionCell(this.db, spec, key);
+            this.collections.set(key, cell);
+        }
+        return cell;
+    }
+    /**
+     * @internal Open `cell` on the server. A refusal sets its error and is not
+     * retried; a lost connection leaves it for the reconnect. A reply that
+     * comes after a resync, or after the cell closed, is dropped and its sub
+     * closed; so is the sub this open replaces.
+     */
+    async openCollection(cell) {
+        if (!this.online)
+            return;
+        const { $window: _, ...spec } = cell.spec;
+        const generation = this.generation;
+        const reply = await this.request({ t: "open_table", ...spec });
+        if (generation !== this.generation || this.collections.get(cell.key) !== cell) {
+            if (reply.t === "rows")
+                this.send({ t: "close", sub: reply.sub });
+            return;
+        }
+        if (reply.t !== "rows") {
+            const lost = reply.t === "error" && reply.kind === "offline";
+            if (!lost) {
+                // A refused reopen (after an invalidation) ends the sub it would have replaced.
+                this.dropSub(cell);
+                cell.failed(reply.t === "error" ? reply.message : `unexpected reply \`${reply.t}\``);
+            }
+            else if (this.haltedWith !== undefined)
+                cell.failed(this.haltedWith);
+            return;
+        }
+        if (cell.sub !== reply.sub)
+            this.dropSub(cell);
+        this.bySub.set(reply.sub, cell);
+        // A scrolled window keeps the rows on screen until its viewport arrives.
+        const scrolled = cell.scrolled;
+        batch(() => {
+            for (const r of reply.records) {
+                const record = this.store.cell(reply.table, r.id);
+                record.applyServer(r);
+                this.persistLater(record);
+            }
+            if (scrolled)
+                cell.opened(reply.sub);
+            else
+                cell.loaded(reply.sub, reply.start, reply.ids, reply.total, reply.complete);
+        });
+        if (scrolled)
+            this.moveWindow(cell);
+    }
+    /** Close the cell's sub on the server and forget it, so its `members` no longer reach the cell. */
+    dropSub(cell) {
+        if (cell.sub === null)
+            return;
+        this.bySub.delete(cell.sub);
+        this.send({ t: "close", sub: cell.sub });
+        cell.sub = null;
+    }
+    /** @internal Move the window; a refused move sets the cell's error. */
+    moveWindow(cell) {
+        if (cell.sub === null || !cell.wantedWindow)
+            return;
+        const generation = this.generation;
+        void this.request({ t: "viewport", sub: cell.sub, start: cell.wantedWindow.start, count: cell.wantedWindow.count }).then((reply) => {
+            if (generation !== this.generation)
+                return;
+            if (reply.t === "members")
+                this.applyMembers(reply);
+            else if (reply.t === "error" && reply.kind !== "offline")
+                cell.failed(reply.message);
+        });
+    }
+    /** @internal */ closeCollection(cell) {
+        if (cell.sub !== null) {
+            this.send({ t: "close", sub: cell.sub });
+            this.bySub.delete(cell.sub);
+        }
+        this.collections.delete(cell.key);
+    }
+    applyMembers(frame) {
+        const cell = this.bySub.get(frame.sub);
+        if (!cell)
+            return;
+        batch(() => {
+            for (const r of frame.records) {
+                const record = this.store.cell(cell.spec.table, r.id);
+                record.applyServer(r);
+                this.persistLater(record);
+            }
+            cell.members(frame.start, frame.ids, frame.total, frame.complete);
+        });
+    }
+    // ------------------------------------------------------------ housekeeping
+    /** Close collections and drop records nothing has shown for a while. */
+    sweep() {
+        const keep = this.keepAliveMs;
+        const now = Date.now();
+        for (const cell of [...this.collections.values()]) {
+            if (!cell.pinned && !cell.wanted() && now - cell.touched > keep)
+                this.closeCollection(cell);
+        }
+        for (const [key, collection] of this.interned) {
+            if (now - collection.created > keep && !collection.cellKeys().some((k) => this.collections.has(k)))
+                this.interned.delete(key);
+        }
+        const listed = new Set([...this.collections.values()].flatMap((c) => c.ids.peek().map((id) => `${c.spec.table}\u0000${id}`)));
+        const drop = [];
+        for (const cell of this.store.allCells()) {
+            const observed = [...cell.fields.values()].some((s) => s.observed) || cell.presence.observed || cell.version.observed;
+            if (observed || cell.pending.size || now - cell.touched < keep || listed.has(`${cell.table}\u0000${cell.id}`))
+                continue;
+            if (this.schema.tables[cell.table]?.load === "instant")
+                continue;
+            this.models.delete(cell);
+            this.store.evict(cell.table, cell.id);
+            if (cell.presence.peek() === "loaded")
+                drop.push([cell.table, cell.id]);
+        }
+        if (drop.length && this.online)
+            this.send({ t: "interest", remove: drop });
+    }
+}

package/dist/client-runs.d.ts

@@ -0,0 +1,18 @@
+import { ClientWrites } from "./client-writes.js";
+import type { RunFrame } from "./protocol.js";
+export declare class ClientRuns extends ClientWrites {
+    /** The runs frames are routed to, by id. More than one may follow an id (two tabs' worth in one page). */
+    private following;
+    private factories;
+    private readonly runHost;
+    /** Route a `run` frame to every run following its id. */
+    protected onRun(frame: RunFrame): void;
+    /**
+     * After a welcome or a resync the server streams nothing to this socket:
+     * send each unanswered invoke again (same id and args, so nothing runs
+     * twice) and attach each running run for a fresh snapshot.
+     */
+    protected resumeRuns(): void;
+    private invokeRun;
+    private runMeta;
+}

package/dist/client-runs.js

@@ -0,0 +1,88 @@
+// Action runs: `db.run.<action>` and `model.$run.<action>` factories, the
+// runs this client follows, their `run` frames, and picking them up again
+// after a reconnect or a resync. Row and toolbar action methods
+// (`issue.close_issue(…)`) are a run awaited to its end.
+import { ClientWrites } from "./client-writes.js";
+import { runFactory } from "./run/run.js";
+/** The feature a server offers when it runs actions as runs. */
+const RUNS = "runs:1";
+export class ClientRuns extends ClientWrites {
+    /** The runs frames are routed to, by id. More than one may follow an id (two tabs' worth in one page). */
+    following = new Map();
+    factories = new Map();
+    /** @internal What the server's `welcome` offered; null before the first. */
+    features = null;
+    runHost = {
+        invoke: (run, args) => this.invokeRun(run, args),
+        request: (frame) => this.request(frame),
+        follow: (run) => {
+            let set = this.following.get(run.id);
+            if (!set)
+                this.following.set(run.id, (set = new Set()));
+            set.add(run);
+        },
+        unfollow: (run) => {
+            const set = this.following.get(run.id);
+            if (set?.delete(run) && set.size === 0)
+                this.following.delete(run.id);
+        },
+    };
+    /** @internal The factory for a project action (`action`) or a row/toolbar action (`table.name`, with `rid` for a row). */
+    runs(action, rid) {
+        const key = `${action}\u0000${rid ?? ""}`;
+        let factory = this.factories.get(key);
+        if (!factory) {
+            factory = runFactory(this.runHost, action, rid, this.runMeta(action));
+            // Row factories are per record; keep only project and toolbar ones.
+            if (rid === undefined)
+                this.factories.set(key, factory);
+        }
+        return factory;
+    }
+    /** @internal A row or toolbar action as one call: start a run, wait for its end. */
+    async invoke(action, rid, args = {}, opts = {}) {
+        const table = action.includes(".") ? action.split(".")[0] : undefined;
+        const cell = table && rid ? this.store.cell(table, rid) : undefined;
+        const optimistic = opts.optimistic && cell ? Object.keys(opts.optimistic) : [];
+        if (cell && opts.optimistic)
+            cell.setPending(opts.optimistic);
+        const outcome = await this.runs(action, rid).start(args).done;
+        if (cell && optimistic.length)
+            cell.settle(optimistic, outcome.ok ? "fresh" : "failed");
+        if (!outcome.ok)
+            return outcome;
+        return { ok: true, value: table && rid ? this.model(table, rid) : undefined };
+    }
+    /** Route a `run` frame to every run following its id. */
+    onRun(frame) {
+        for (const run of [...(this.following.get(frame.run) ?? [])])
+            run.apply(frame);
+    }
+    /**
+     * After a welcome or a resync the server streams nothing to this socket:
+     * send each unanswered invoke again (same id and args, so nothing runs
+     * twice) and attach each running run for a fresh snapshot.
+     */
+    resumeRuns() {
+        for (const set of [...this.following.values()])
+            for (const run of [...set])
+                run.resume();
+    }
+    async invokeRun(run, args) {
+        const halted = this.haltedWith;
+        if (halted !== undefined)
+            return { t: "error", id: 0, kind: "unavailable", message: halted };
+        // Not connected: answered as not sent; `resumeRuns` sends it after the welcome.
+        if (!this.online)
+            return { t: "error", id: 0, kind: "offline", message: "not connected" };
+        if (!this.features?.has(RUNS))
+            return { t: "error", id: 0, kind: "failed", message: "the server doesn't support runs (no `runs:1` in its welcome)" };
+        const frame = args === undefined ? { t: "invoke", run: run.id } : { t: "invoke", run: run.id, action: run.action, rid: run.recordId, args: args };
+        return this.request(frame);
+    }
+    runMeta(action) {
+        const [table, name] = action.includes(".") ? action.split(".") : [undefined, action];
+        const meta = table ? this.schema.tables[table]?.actions[name] : this.schema.actions[name];
+        return meta ?? {};
+    }
+}

package/dist/client-writes.d.ts

@@ -0,0 +1,14 @@
+import { ClientLoading } from "./client-loading.js";
+import type { ActionResult } from "./types.js";
+export declare class ClientWrites extends ClientLoading {
+    /** Choices for a form field whose options come from a script. */
+    options(action: string, field: string, form?: Record<string, unknown>): Promise<{
+        value: unknown;
+        label: string;
+    }[]>;
+    /** Undo your last confirmed edit, if nobody has changed those fields since. */
+    undo(): Promise<ActionResult<undefined>>;
+    /** Flashes in one microtask travel as one `batch` (not a transaction). After a halt, a write settles at once with its error. */
+    private enqueue;
+    protected flush(): Promise<void>;
+}

package/dist/client-writes.js

@@ -0,0 +1,114 @@
+// Writing: optimistic edits batched per microtask, deletes, undo, and edits
+// queued while offline.
+import { ClientLoading } from "./client-loading.js";
+import { fail, failFrom, pick, sameValue, uuidv7 } from "./util.js";
+export class ClientWrites extends ClientLoading {
+    /** Choices for a form field whose options come from a script. */
+    async options(action, field, form = {}) {
+        const reply = await this.request({ t: "options", action, field, form });
+        return reply.t === "options_result" ? reply.items : [];
+    }
+    // ------------------------------------------------------------ writes
+    /** @internal Optimistic write. No `id` inserts (an `input.id` is kept). */
+    async write(table, id, patch, opts = {}) {
+        let cell;
+        let before;
+        const keys = Object.keys(patch).filter((k) => k !== "id");
+        if (id) {
+            cell = this.store.cell(table, id);
+            before = pick(cell.snapshot(), keys);
+            cell.setPending(pick(patch, keys));
+        }
+        else {
+            const local = String(patch.id ?? uuidv7());
+            id = local.includes(":") ? local : `${table}:${local}`;
+            cell = this.store.cell(table, id);
+            cell.setPending({ ...pick(patch, keys) });
+            patch = { ...patch, id: local.includes(":") ? local.split(":").slice(1).join(":") : local };
+        }
+        const item = before ? { table, rid: id, patch: pick(patch, keys) } : { table, patch };
+        const frame = await this.enqueue(item);
+        if (frame.t === "flashed") {
+            let target = cell;
+            if (frame.rid !== cell.id) {
+                // The server named it (`client_order:…`): move to the real id.
+                target = this.store.cell(table, frame.rid);
+                cell.markRemoved();
+                this.store.evict(table, cell.id);
+            }
+            if (frame.record)
+                target.applyServer(frame.record);
+            target.settle(keys, "fresh");
+            this.persistLater(target);
+            if (before && opts.recordUndo !== false)
+                this.undoStack.push({ table, id: target.id, before, after: pick(patch, keys) });
+            if (this.undoStack.length > 100)
+                this.undoStack.shift();
+            return { ok: true, value: this.model(table, target.id) };
+        }
+        const fieldErrors = frame.t === "rejected" ? (frame.field_errors ?? {}) : {};
+        const message = frame.t === "rejected" || frame.t === "error" ? frame.message : "write failed";
+        cell.settle(keys, "failed", Object.keys(fieldErrors).length ? fieldErrors : { $: message });
+        if (!before)
+            cell.markRemoved();
+        return { ok: false, error: { kind: frame.t === "error" ? frame.kind : "invalid", message, fieldErrors } };
+    }
+    /** @internal */ async remove(table, id) {
+        const cell = this.store.cell(table, id);
+        const backup = cell.snapshot();
+        cell.markRemoved();
+        const reply = await this.request({ t: "delete", table, rid: id });
+        if (reply.t === "flashed")
+            return { ok: true, value: undefined };
+        cell.applyServer(backup, "failed");
+        return failFrom(reply);
+    }
+    /** Undo your last confirmed edit, if nobody has changed those fields since. */
+    async undo() {
+        const last = this.undoStack.pop();
+        if (!last)
+            return fail("invalid", "nothing to undo");
+        const now = this.store.cell(last.table, last.id).snapshot();
+        const keys = Object.keys(last.after).filter((k) => sameValue(now[k], last.after[k]));
+        if (keys.length === 0)
+            return fail("conflict", "someone changed it since");
+        const result = await this.write(last.table, last.id, pick(last.before, keys), { recordUndo: false });
+        return result.ok ? { ok: true, value: undefined } : result;
+    }
+    /** Flashes in one microtask travel as one `batch` (not a transaction). After a halt, a write settles at once with its error. */
+    enqueue(item) {
+        return new Promise((resolve) => {
+            const halted = this.haltedWith;
+            if (halted !== undefined) {
+                const kind = this.connection.peek().status === "refused" ? "forbidden" : "unavailable";
+                return resolve({ t: "error", id: 0, kind, message: halted });
+            }
+            if (!this.online) {
+                if (!this.storage)
+                    return resolve({ t: "error", id: 0, kind: "offline", message: "not connected" });
+                // Offline with a mirror: keep it and send on reconnect.
+                this.outbox.push(item);
+                void this.storage.save({ outbox: this.outbox });
+                this.flashQueue.push({ item, resolve });
+                return;
+            }
+            this.flashQueue.push({ item, resolve });
+            if (this.flashQueue.length === 1)
+                queueMicrotask(() => this.flush());
+        });
+    }
+    async flush() {
+        const queue = this.flashQueue.splice(0);
+        if (queue.length === 0)
+            return;
+        const reply = queue.length === 1 ? await this.request({ t: "flash", ...queue[0].item }) : await this.request({ t: "batch", items: queue.map((q) => q.item) });
+        if (reply.t === "batch_result")
+            reply.results.forEach((r, i) => queue[i].resolve(r));
+        else
+            queue.forEach((q) => q.resolve(reply));
+        if (this.outbox.length && this.online) {
+            this.outbox = [];
+            void this.storage?.save({ outbox: [] });
+        }
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import { ClientConnection } from "./client-connection.js";
+import type { Storage } from "./persist.js";
+import { type InputOf, type ModelOf, type ProjectActions, type TableActionsOf, type TableHandle, type TableName, type Tables } from "./table.js";
+import type { Transport } from "./transport.js";
+import type { FieldMeta, Hydrated, SchemaMeta, SchemaTypes } from "./types.js";
+export interface VantageOptions {
+    /** The `schema` const from vantage.gen.ts. */
+    schema: SchemaMeta;
+    /** `ws(s)://host/v1/ws`; defaults to the page's origin, and is required outside a browser. */
+    url?: string;
+    /** Sent in `hello`: a token, or a function returning one, called on every connect. */
+    token?: string | (() => string | undefined | Promise<string | undefined>);
+    /** Offline mirror of `persist: true` tables (see ./persist). */
+    storage?: Storage;
+    /** Swap the WebSocket (tests use the MockServer). */
+    transport?: Transport;
+    /** How long an unread record or collection is kept after nothing shows it. Default 30 s. */
+    keepAliveMs?: number;
+    /** The server's frontend was rebuilt (`{t:"reload"}`). Default: `location.reload()` in a browser, nothing elsewhere. */
+    onReload?: () => void;
+}
+export type VantageDb<S extends SchemaTypes> = Vantage<S> & Tables<S>;
+export declare function createVantage<S extends SchemaTypes>(options: VantageOptions): VantageDb<S>;
+export declare class Vantage<S extends SchemaTypes = SchemaTypes> extends ClientConnection {
+    /** `db.run.magic_promotion.start({ bakery })`: project actions, as runs. */
+    readonly run: ProjectActions<S>;
+    constructor(options: VantageOptions);
+    table<T extends TableName<S>>(name: T): TableHandle<ModelOf<S, T>, InputOf<S, T>, TableActionsOf<S, T>>;
+    /** Run loads ahead of navigation; resolves when they're done. */
+    preload(fn: () => unknown): Promise<void>;
+}
+export type { FieldMeta, Hydrated, ProjectActions, TableHandle, Tables };