@vantage-ui/client 0.0.0-stage → 0.4.3

package/dist/run/messages.js

@@ -0,0 +1,42 @@
+// A run's messages on the client: the last ones kept (like the server's
+// buffer) and the listeners `run.on` registered.
+import { State } from "../signal.js";
+/** A run's messages kept on the client, like the server's buffer. */
+const KEPT = 100;
+/** A message as `run.messages` holds it, without its wire seq. */
+const stored = ({ name, payload }) => ({ name, payload });
+export class RunMessages {
+    list = new State([]);
+    listeners = new Map();
+    /** The kept messages, oldest first; reactive. */
+    get() {
+        return this.list.get();
+    }
+    on(name, fn) {
+        let set = this.listeners.get(name);
+        if (!set)
+            this.listeners.set(name, (set = new Set()));
+        set.add(fn);
+        return () => void set.delete(fn);
+    }
+    clear() {
+        this.list.set([]);
+    }
+    /** A snapshot's buffer replaces the kept messages; the listeners hear those that are `news`. */
+    replace(messages, news) {
+        this.list.set(messages.map(stored));
+        for (const message of messages)
+            if (news(message))
+                this.notify(message);
+    }
+    /** A live message: kept, and heard by the listeners. */
+    received(message) {
+        const list = [...this.list.peek(), stored(message)];
+        this.list.set(list.length > KEPT ? list.slice(-KEPT) : list);
+        this.notify(message);
+    }
+    notify(message) {
+        for (const fn of this.listeners.get(message.name) ?? [])
+            fn(message.payload);
+    }
+}

package/dist/run/outcome.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorKind, ServerFrame } from "../protocol.js";
+import type { ActionError } from "../types.js";
+import type { RunError } from "./types.js";
+type Failed = {
+    ok: false;
+    error: ActionError;
+};
+/** A refused `run_set`/`run_cancel` reply as a failed result. */
+export declare function refused(reply: ServerFrame): Failed;
+/** A run's error code as an `ActionError` kind, mirroring the server's. */
+export declare function kindOf(code: RunError["code"] | undefined): ErrorKind;
+export {};

package/dist/run/outcome.js

@@ -0,0 +1,27 @@
+// A run's refusals and outcomes as `ActionResult`s.
+import { fail } from "../util.js";
+/** A refused `run_set`/`run_cancel` reply as a failed result. */
+export function refused(reply) {
+    if (reply.t !== "error")
+        return fail("failed", `unexpected reply \`${reply.t}\``);
+    return fail(reply.code ? kindOf(reply.code) : reply.kind, reply.message);
+}
+/** A run's error code as an `ActionError` kind, mirroring the server's. */
+export function kindOf(code) {
+    switch (code) {
+        case "conflict":
+            return "conflict";
+        case "expired":
+            return "not_found";
+        case "forbidden":
+            return "forbidden";
+        case "invalid":
+            return "invalid";
+        case "limit":
+            return "unavailable";
+        case "offline":
+            return "offline";
+        default:
+            return "failed";
+    }
+}

package/dist/run/run.d.ts

@@ -0,0 +1,82 @@
+import type { Json, ServerFrame } from "../protocol.js";
+import type { RunMeta } from "../schema-meta.js";
+import type { ActionResult } from "../types.js";
+import type { Run, RunError, RunFactory, RunStatus, RunTypes, StartOptions } from "./types.js";
+/** What a run needs from the client. */
+export interface RunHost {
+    /**
+     * Send `invoke` for `run`: with `args` the start, without them an attach.
+     * Resolves `offline` without sending while the client is disconnected.
+     */
+    invoke(run: RunImpl, args: Record<string, unknown> | undefined): Promise<ServerFrame>;
+    request(frame: {
+        t: "run_set";
+        run: string;
+        name: string;
+        value: Json;
+    } | {
+        t: "run_cancel";
+        run: string;
+    }): Promise<ServerFrame>;
+    /** Route `run` frames for `run.id` to it, or stop. */
+    follow(run: RunImpl): void;
+    unfollow(run: RunImpl): void;
+}
+export declare class RunImpl implements Run<RunTypes> {
+    private host;
+    readonly action: string;
+    private rid;
+    private idCell;
+    private statusCell;
+    private resultCell;
+    private errorCell;
+    private variables;
+    private messageLog;
+    /** What `start` sent;`undefined` for a run this client only attached to. */
+    private startArgs;
+    /** This client started the run and no snapshot came yet: its messages are news, not history. */
+    private firstSnapshotIsNews;
+    /** An attach for a fresh snapshot is on its way; more gaps don't ask again. */
+    private reattaching;
+    private settle?;
+    private donePromise;
+    /** Resolves once the run leaves `starting`; an input written before then waits for it. */
+    private started;
+    private markStarted?;
+    readonly state: Readonly<Record<string, unknown>>;
+    constructor(host: RunHost, action: string, rid: string | undefined, meta: RunMeta);
+    get id(): string;
+    get status(): RunStatus;
+    get result(): unknown;
+    get error(): RunError | null;
+    get messages(): never;
+    get done(): Promise<ActionResult<unknown>>;
+    start(args?: object, options?: StartOptions): this;
+    attach(run: string): this;
+    forget(): void;
+    on(name: string, fn: (payload: never) => void): () => void;
+    set(name: string, value: unknown): Promise<ActionResult<undefined>>;
+    cancel(): Promise<ActionResult<undefined>>;
+    private begin;
+    /** Send the start, or an attach for a run this client didn't start. */
+    private send;
+    private reattach;
+    /** Send `invoke`; a reply that arrives after the run moved to another id is ignored. */
+    private request;
+    /** Back to `idle`; whoever still waits on the previous run hears `reason`. */
+    private reset;
+    private setStatus;
+    private answered;
+    private finish;
+    private finishWith;
+    /**
+     * Whether a snapshot's message is news to the listeners. In the first
+     * snapshot of a run this client started, all are. In a later one (after
+     * a reconnect, a resync or a missed frame) those past the last applied
+     * seq are: they went out while this client wasn't following. The first
+     * snapshot after `attach` or a reload is history.
+     */
+    private isNews;
+}
+/** The factory for `action`: `start`, `attach`, `idle`. */
+export declare function runFactory<T extends RunTypes>(host: RunHost, action: string, rid: string | undefined, meta: RunMeta): RunFactory<T>;

package/dist/run/run.js

@@ -0,0 +1,246 @@
+// One run of an action, as the client follows it: its status, shared
+// variables, messages, outcome, and the input writes it sends.
+//
+// A run survives a lost connection and a resync: an invoke that got no
+// answer is sent again with the same id and args after the welcome (the
+// server attaches instead of running twice), and a running run attaches
+// again for a fresh snapshot.
+import { State, batch } from "../signal.js";
+import { fail, uuidv7 } from "../util.js";
+import { classify, isFinal } from "./frames.js";
+import { RunMessages } from "./messages.js";
+import { kindOf, refused } from "./outcome.js";
+import { RunVariables } from "./variables.js";
+export class RunImpl {
+    host;
+    action;
+    rid;
+    idCell = new State("");
+    statusCell = new State("idle");
+    resultCell = new State(undefined);
+    errorCell = new State(null);
+    variables;
+    messageLog = new RunMessages();
+    /** What `start` sent;`undefined` for a run this client only attached to. */
+    startArgs;
+    /** This client started the run and no snapshot came yet: its messages are news, not history. */
+    firstSnapshotIsNews = false;
+    /** An attach for a fresh snapshot is on its way; more gaps don't ask again. */
+    reattaching = false;
+    settle;
+    donePromise;
+    /** Resolves once the run leaves `starting`; an input written before then waits for it. */
+    started;
+    markStarted;
+    /** @internal The seq of the last frame applied; -1 before the first snapshot. */
+    lastSeq = -1;
+    state;
+    constructor(host, action, rid, meta) {
+        this.host = host;
+        this.action = action;
+        this.rid = rid;
+        this.variables = new RunVariables(meta);
+        this.state = this.variables.state;
+        this.reset("");
+    }
+    get id() {
+        return this.idCell.get();
+    }
+    get status() {
+        return this.statusCell.get();
+    }
+    get result() {
+        return this.resultCell.get();
+    }
+    get error() {
+        return this.errorCell.get();
+    }
+    get messages() {
+        return this.messageLog.get();
+    }
+    get done() {
+        return this.donePromise;
+    }
+    /** @internal The record a row action runs on. */
+    get recordId() {
+        return this.rid;
+    }
+    /** @internal Whether the client writes `name` (an `input: true` variable). */
+    isInput(name) {
+        return this.variables.isInput(name);
+    }
+    start(args, options = {}) {
+        this.begin(options.run ?? uuidv7(), { ...(args ?? {}) });
+        this.firstSnapshotIsNews = true;
+        this.send();
+        return this;
+    }
+    attach(run) {
+        this.begin(run, undefined);
+        this.reattach();
+        return this;
+    }
+    forget() {
+        this.host.unfollow(this);
+        this.reset("the run was forgotten");
+    }
+    /** @internal After a welcome or a resync: send an unanswered invoke again, or attach for a fresh snapshot. */
+    resume() {
+        const status = this.statusCell.peek();
+        if (status === "starting")
+            this.send();
+        else if (status === "running") {
+            this.reattaching = false;
+            this.reattach();
+        }
+    }
+    on(name, fn) {
+        return this.messageLog.on(name, fn);
+    }
+    async set(name, value) {
+        if (this.statusCell.peek() === "starting")
+            await this.started;
+        const id = this.idCell.peek();
+        if (!id || this.statusCell.peek() !== "running")
+            return fail("conflict", "the run isn't running");
+        const reply = await this.variables.write(name, value, () => this.host.request({ t: "run_set", run: id, name, value: value }));
+        return reply.t === "ack" ? { ok: true, value: undefined } : refused(reply);
+    }
+    async cancel() {
+        const id = this.idCell.peek();
+        if (!id)
+            return fail("conflict", "the run hasn't started");
+        const reply = await this.host.request({ t: "run_cancel", run: id });
+        return reply.t === "ack" ? { ok: true, value: undefined } : refused(reply);
+    }
+    /** @internal Apply a `run` frame; after a missed one, attach again (once) for a fresh snapshot. */
+    apply(frame) {
+        const kind = classify(frame, this.lastSeq);
+        if (kind === "stale")
+            return;
+        if (kind === "gap") {
+            if (!this.reattaching)
+                this.reattach();
+            return;
+        }
+        batch(() => {
+            for (const [name, value] of Object.entries(frame.state ?? {}))
+                this.variables.fromServer(name, value);
+            if (kind === "snapshot") {
+                this.reattaching = false;
+                this.messageLog.replace(frame.messages ?? [], (message) => this.isNews(message));
+                this.firstSnapshotIsNews = false;
+            }
+            else {
+                for (const message of frame.messages ?? [])
+                    this.messageLog.received(message);
+            }
+            this.lastSeq = frame.seq;
+            if (frame.status === "running")
+                this.setStatus("running");
+            if (isFinal(frame))
+                this.finish(frame);
+        });
+    }
+    begin(id, args) {
+        this.host.unfollow(this);
+        this.reset("the run was restarted");
+        this.startArgs = args;
+        this.idCell.set(id);
+        this.statusCell.set("starting");
+        this.host.follow(this);
+    }
+    /** Send the start, or an attach for a run this client didn't start. */
+    send() {
+        this.request(this.startArgs);
+    }
+    reattach() {
+        this.reattaching = true;
+        this.request(undefined);
+    }
+    /** Send `invoke`; a reply that arrives after the run moved to another id is ignored. */
+    request(args) {
+        const id = this.idCell.peek();
+        void this.host.invoke(this, args).then((reply) => {
+            if (this.idCell.peek() === id)
+                this.answered(reply);
+        });
+    }
+    /** Back to `idle`; whoever still waits on the previous run hears `reason`. */
+    reset(reason) {
+        this.settle?.(fail("conflict", reason));
+        this.markStarted?.();
+        batch(() => {
+            this.variables.reset();
+            this.messageLog.clear();
+            this.resultCell.set(undefined);
+            this.errorCell.set(null);
+            this.idCell.set("");
+            this.statusCell.set("idle");
+        });
+        this.startArgs = undefined;
+        this.firstSnapshotIsNews = false;
+        this.reattaching = false;
+        this.lastSeq = -1;
+        this.donePromise = new Promise((resolve) => (this.settle = resolve));
+        this.started = new Promise((resolve) => (this.markStarted = resolve));
+    }
+    setStatus(status) {
+        this.statusCell.set(status);
+        if (status !== "starting" && status !== "idle")
+            this.markStarted?.();
+    }
+    answered(reply) {
+        if (reply.t === "result") {
+            if (reply.status !== "done" && this.statusCell.peek() === "starting")
+                this.setStatus("running");
+            return;
+        }
+        // Not answered: the run may well be going. It's sent again after the welcome.
+        if (reply.t !== "error" || reply.kind === "offline")
+            return;
+        this.reattaching = false;
+        const code = reply.code ?? "failed";
+        this.finishWith("failed", undefined, { code, message: reply.message });
+    }
+    finish(frame) {
+        const error = frame.error ? { code: frame.error.code, message: frame.error.message } : null;
+        this.finishWith(frame.status, frame.result, error);
+    }
+    finishWith(status, result, error) {
+        batch(() => {
+            this.resultCell.set(result);
+            this.errorCell.set(error);
+            this.setStatus(status);
+        });
+        this.host.unfollow(this);
+        if (status === "done")
+            this.settle?.({ ok: true, value: result });
+        else if (status === "cancelled")
+            this.settle?.(fail("conflict", "the run was cancelled"));
+        else
+            this.settle?.(fail(kindOf(error?.code), error?.message ?? "the run failed"));
+    }
+    /**
+     * Whether a snapshot's message is news to the listeners. In the first
+     * snapshot of a run this client started, all are. In a later one (after
+     * a reconnect, a resync or a missed frame) those past the last applied
+     * seq are: they went out while this client wasn't following. The first
+     * snapshot after `attach` or a reload is history.
+     */
+    isNews(message) {
+        if (this.firstSnapshotIsNews)
+            return true;
+        return this.lastSeq >= 0 && message.seq !== undefined && message.seq > this.lastSeq;
+    }
+}
+/** The factory for `action`: `start`, `attach`, `idle`. */
+export function runFactory(host, action, rid, meta) {
+    const make = () => new RunImpl(host, action, rid, meta);
+    return {
+        action,
+        start: (...args) => make().start(...args),
+        attach: (run) => make().attach(run),
+        idle: make,
+    };
+}

package/dist/run/storage.d.ts

@@ -0,0 +1,3 @@
+export declare function savedRun(key: string): string | undefined;
+export declare function saveRun(key: string, run: string): void;
+export declare function forgetRun(key: string): void;

package/dist/run/storage.js

@@ -0,0 +1,20 @@
+// Where `useRun(…, { key })` keeps a run's id across page reloads: the
+// tab's `sessionStorage`, or nowhere when there is none (Node, tests).
+const PREFIX = "vantage.run.";
+function session() {
+    try {
+        return globalThis.sessionStorage ?? undefined;
+    }
+    catch {
+        return undefined; // storage disabled (privacy mode, sandboxed frame)
+    }
+}
+export function savedRun(key) {
+    return session()?.getItem(PREFIX + key) ?? undefined;
+}
+export function saveRun(key, run) {
+    session()?.setItem(PREFIX + key, run);
+}
+export function forgetRun(key) {
+    session()?.removeItem(PREFIX + key);
+}

package/dist/run/types.d.ts

@@ -0,0 +1,92 @@
+import type { Json, RunCode } from "../protocol.js";
+import type { ActionResult } from "../types.js";
+/**
+ * One action's run types, as `generate` emits them: what it takes (`args`),
+ * the variables it shares (`state`), the ones a client may write (`inputs`)
+ * and the messages it sends.
+ */
+export interface RunTypes {
+    args: object;
+    state: object;
+    inputs: object;
+    messages: object;
+}
+/**
+ * `idle` before `start`; `starting` until the server answers; then the
+ * server's `running`, `done`, `failed` or `cancelled`.
+ */
+export type RunStatus = "idle" | "starting" | "running" | "done" | "failed" | "cancelled";
+/** Why a run was refused or failed. `offline`: the client wasn't connected. */
+export interface RunError {
+    readonly code: RunCode | "offline";
+    readonly message: string;
+}
+/** The messages the framework sends for any action: a body's `notify(text)` and `log(text)`. */
+export interface FrameworkMessages {
+    "vantage.notify": {
+        text: string;
+    };
+    "vantage.log": {
+        text: string;
+    };
+}
+/** Every message a run of `T` may send: its own and the framework's. */
+export type MessagesOf<T extends RunTypes> = T["messages"] & FrameworkMessages;
+/** A message a run sent: one the action declares, or a framework one (`vantage.notify`, `vantage.log`). */
+export type RunMessageOf<M> = {
+    [K in keyof M & string]: {
+        readonly name: K;
+        readonly payload: M[K];
+    };
+}[keyof M & string] | {
+    readonly name: `vantage.${string}`;
+    readonly payload: Json;
+};
+export interface StartOptions {
+    /** The run id; a new UUIDv7 when not given. Invoking an id again attaches to that run instead of starting another. */
+    run?: string;
+}
+export type StartArgs<A> = {} extends A ? [args?: A, options?: StartOptions] : [args: A, options?: StartOptions];
+/** `db.run.<action>` and `model.$run.<action>`: starts runs of one action, or attaches to one. */
+export interface RunFactory<T extends RunTypes = RunTypes> {
+    readonly action: string;
+    start(...args: StartArgs<T["args"]>): Run<T>;
+    /** Follow a run started earlier (by this page before a reload, or another tab). */
+    attach(run: string): Run<T>;
+    /** A run that hasn't started: `start` it later. */
+    idle(): Run<T>;
+}
+/** One run of an action. Every getter is reactive. */
+export interface Run<T extends RunTypes = RunTypes> {
+    readonly action: string;
+    /** The run id; empty while `idle`. */
+    readonly id: string;
+    readonly status: RunStatus;
+    /** The shared variables, as the server last sent them (an input shows your write at once). */
+    readonly state: Readonly<T["state"]>;
+    /** The body's return value, once `done`. Sent as the body returns it, not filtered by the API's column whitelists. */
+    readonly result: unknown;
+    readonly error: RunError | null;
+    /** The messages so far (the last 100), oldest first; after an attach, the run's buffer. */
+    readonly messages: readonly RunMessageOf<T["messages"]>[];
+    /**
+     * Call `fn` for each message `name` that arrives from now on, the
+     * framework's `vantage.notify` and `vantage.log` included. A run this
+     * client started also delivers what it sent before the first snapshot;
+     * after an attach, earlier messages are only in `messages`. Returns the
+     * unsubscribe.
+     */
+    on<K extends keyof MessagesOf<T> & string>(name: K, fn: (payload: MessagesOf<T>[K]) => void): () => void;
+    /** Write an input variable; shown at once, rolled back if the server refuses. */
+    set<K extends keyof T["inputs"] & string>(name: K, value: T["inputs"][K]): Promise<ActionResult<undefined>>;
+    /** Stop the run at its next wait, sleep or host call. */
+    cancel(): Promise<ActionResult<undefined>>;
+    /** Start this run (again, with a new id when it had one); returns it. */
+    start(...args: StartArgs<T["args"]>): Run<T>;
+    /** Follow run `run` in place of whatever this one was. */
+    attach(run: string): Run<T>;
+    /** Stop following and go back to `idle`; the server's run is not touched. `start` doesn't need it first. */
+    forget(): void;
+    /** Settles once the run is over: the result, or why it failed, was cancelled or was refused. */
+    readonly done: Promise<ActionResult<unknown>>;
+}

package/dist/run/types.js

@@ -0,0 +1,3 @@
+// The public types of action runs: a run factory per action, and the run
+// it starts or attaches to.
+export {};

package/dist/run/variables.d.ts

@@ -0,0 +1,26 @@
+import type { ServerFrame } from "../protocol.js";
+import type { RunMeta } from "../schema-meta.js";
+export declare class RunVariables {
+    private meta;
+    private cells;
+    /** The values the server last sent; an input rolls back to these. */
+    private server;
+    /** Input writes in flight, per variable, and the ones the server changed meanwhile. */
+    private pending;
+    private changedWhilePending;
+    /** The variables as `run.state`: reading one tracks its signal. */
+    readonly state: Readonly<Record<string, unknown>>;
+    constructor(meta: RunMeta);
+    /** Whether the client writes `name` (an `input: true` variable). */
+    isInput(name: string): boolean;
+    /** Back to the declared defaults; writes still in flight roll back to them. */
+    reset(): void;
+    /** A value the server sent; it shows unless a write of `name` is in flight. */
+    fromServer(name: string, value: unknown): void;
+    /**
+     * Show `value` at once and `send` it. When the last write of `name` in
+     * flight is refused, or the server moved on meanwhile, its value wins.
+     */
+    write(name: string, value: unknown, send: () => Promise<ServerFrame>): Promise<ServerFrame>;
+    private cell;
+}

package/dist/run/variables.js

@@ -0,0 +1,70 @@
+// A run's shared variables on the client: one signal each, so a component
+// re-renders only for what it reads, and the optimistic input writes that
+// roll back to the server's value when refused or overtaken.
+import { State } from "../signal.js";
+export class RunVariables {
+    meta;
+    cells = new Map();
+    /** The values the server last sent; an input rolls back to these. */
+    server = new Map();
+    /** Input writes in flight, per variable, and the ones the server changed meanwhile. */
+    pending = new Map();
+    changedWhilePending = new Set();
+    /** The variables as `run.state`: reading one tracks its signal. */
+    state;
+    constructor(meta) {
+        this.meta = meta;
+        const declared = () => meta.state ?? {};
+        this.state = new Proxy({}, {
+            get: (_, name) => (typeof name === "string" ? this.cell(name).get() : undefined),
+            has: (_, name) => typeof name === "string" && name in declared(),
+            ownKeys: () => Object.keys(declared()),
+            getOwnPropertyDescriptor: (_, name) => (typeof name === "string" && name in declared() ? { enumerable: true, configurable: true, value: this.cell(name).peek() } : undefined),
+        });
+    }
+    /** Whether the client writes `name` (an `input: true` variable). */
+    isInput(name) {
+        return this.meta.state?.[name]?.input === true;
+    }
+    /** Back to the declared defaults; writes still in flight roll back to them. */
+    reset() {
+        this.pending.clear();
+        this.changedWhilePending.clear();
+        for (const [name, info] of Object.entries(this.meta.state ?? {}))
+            this.fromServer(name, info.default);
+    }
+    /** A value the server sent; it shows unless a write of `name` is in flight. */
+    fromServer(name, value) {
+        this.server.set(name, value);
+        if (this.pending.has(name))
+            this.changedWhilePending.add(name);
+        else
+            this.cell(name).set(value);
+    }
+    /**
+     * Show `value` at once and `send` it. When the last write of `name` in
+     * flight is refused, or the server moved on meanwhile, its value wins.
+     */
+    async write(name, value, send) {
+        const cell = this.cell(name);
+        cell.set(value);
+        this.pending.set(name, (this.pending.get(name) ?? 0) + 1);
+        const reply = await send();
+        const left = (this.pending.get(name) ?? 1) - 1;
+        if (left > 0) {
+            this.pending.set(name, left);
+            return reply;
+        }
+        this.pending.delete(name);
+        if (reply.t !== "ack" || this.changedWhilePending.has(name))
+            cell.set(this.server.get(name));
+        this.changedWhilePending.delete(name);
+        return reply;
+    }
+    cell(name) {
+        let cell = this.cells.get(name);
+        if (!cell)
+            this.cells.set(name, (cell = new State(this.meta.state?.[name]?.default)));
+        return cell;
+    }
+}