@vantage-ui/client 0.0.0-stage → 0.4.3

package/dist/schema-meta.d.ts

@@ -0,0 +1,91 @@
+/** The shape `vantage-client generate` emits as `Schema`. */
+export interface SchemaTypes {
+    models: object;
+    fields: object;
+    inputs: object;
+    tableActions: object;
+    projectActions: object;
+}
+/** Runtime metadata (`schema` const in vantage.gen.ts). */
+export interface SchemaMeta {
+    readonly hash: string;
+    readonly tables: {
+        readonly [table: string]: TableMeta;
+    };
+    readonly actions: {
+        readonly [action: string]: ActionMeta;
+    };
+}
+/** A project action a client can run. */
+export interface ActionMeta extends RunMeta {
+    readonly key: string;
+    readonly kind?: string;
+    readonly fields: readonly FieldMeta[];
+}
+/** What a run of an action shares: its variables, and the messages it may send. Absent in older generated files. */
+export interface RunMeta {
+    readonly state?: {
+        readonly [name: string]: {
+            readonly type: string;
+            readonly default: unknown;
+            readonly input: boolean;
+        };
+    };
+    readonly messages?: readonly string[];
+}
+export interface TableMeta {
+    readonly key: string;
+    readonly load: "instant" | "lazy" | "manual";
+    readonly persist: boolean;
+    readonly live: unknown;
+    readonly readOnly: boolean;
+    readonly idColumn: string;
+    readonly title: string | null;
+    readonly collectionLimit: number;
+    /** Columns a collection may sort by; null when any column may be. */
+    readonly sortable?: readonly string[] | null;
+    /** Columns `where` may name. */
+    readonly filter?: readonly string[] | null;
+    /** The sort of a collection opened without one. */
+    readonly defaultSort?: {
+        readonly column: string;
+        readonly direction: "asc" | "desc";
+    } | null;
+    readonly columns: {
+        readonly [column: string]: {
+            readonly type: string;
+            readonly readonly?: boolean;
+            readonly hidden?: boolean;
+            readonly enum?: readonly unknown[];
+        };
+    };
+    readonly references: {
+        readonly [name: string]: {
+            readonly column: string;
+            readonly table: string;
+        };
+    };
+    readonly hasMany: {
+        readonly [name: string]: {
+            readonly table: string;
+            readonly foreignKey: string;
+        };
+    };
+    readonly actions: {
+        readonly [name: string]: RunMeta & {
+            readonly perRow: boolean;
+            readonly label: string;
+            readonly fields: readonly FieldMeta[];
+        };
+    };
+}
+export interface FieldMeta {
+    readonly name: string;
+    readonly type: string;
+    readonly label: string | null;
+    readonly required: boolean;
+    readonly choices: readonly string[] | null;
+    readonly default: unknown;
+    readonly widget: string | null;
+    readonly options: boolean;
+}

package/dist/schema-meta.js

@@ -0,0 +1,3 @@
+// The schema types a generated `vantage.gen.ts` carries: `Schema` (its
+// types) and `schema` (the runtime metadata the client builds models from).
+export {};

package/dist/signal.d.ts

@@ -0,0 +1,45 @@
+type Subscriber = () => void;
+export interface StateHooks {
+    /** First subscriber attached. */
+    observed?(): void;
+    /** Last subscriber left. */
+    unobserved?(): void;
+}
+export declare class State<T> {
+    private value;
+    private readonly hooks?;
+    private subscribers;
+    /** Bumps on every change; lets a late subscriber detect a missed change. */
+    version: number;
+    constructor(value: T, hooks?: StateHooks | undefined);
+    get(): T;
+    peek(): T;
+    set(value: T): void;
+    /** Mark changed without replacing the value (mutated in place). */
+    touch(): void;
+    get observed(): boolean;
+    subscribe(fn: Subscriber): () => void;
+    private notify;
+}
+export declare function batch<T>(fn: () => T): T;
+/** Run `fn`, collecting the states it reads (with their versions). */
+export declare function track<T>(fn: () => T): [T, Map<State<unknown>, number>];
+/** Read without recording dependencies. */
+export declare function untracked<T>(fn: () => T): T;
+/** A tracked computation with listeners: the engine behind `observer()`. */
+export declare class Reaction {
+    private deps;
+    private unsubscribers;
+    private listeners;
+    version: number;
+    /** Run `fn` and make its reads this reaction's dependencies. */
+    track<T>(fn: () => T): T;
+    subscribe: (listener: Subscriber) => (() => void);
+    getVersion: () => number;
+    dispose(): void;
+    private sync;
+    private changed;
+}
+/** Re-run `fn` whenever what it read changes. Returns a stop function. */
+export declare function autorun(fn: () => void): () => void;
+export {};

package/dist/signal.js

@@ -0,0 +1,163 @@
+// Fine-grained reactivity, about 150 lines.
+//
+// - `State` holds a value. Reading it inside `track()` records a dependency.
+// - `batch()` delays notifications until the outermost batch ends, so one
+//   server frame touching forty fields notifies each subscriber once.
+// - `Reaction` is what a component render (or `useLive`) tracks with. It
+//   subscribes to its dependencies only while something listens to it, so a
+//   render React throws away never leaks subscriptions.
+let tracking = null;
+let batchDepth = 0;
+const queued = new Set();
+export class State {
+    value;
+    hooks;
+    subscribers = new Set();
+    /** Bumps on every change; lets a late subscriber detect a missed change. */
+    version = 0;
+    constructor(value, hooks) {
+        this.value = value;
+        this.hooks = hooks;
+    }
+    get() {
+        if (tracking && !tracking.has(this))
+            tracking.set(this, this.version);
+        return this.value;
+    }
+    peek() {
+        return this.value;
+    }
+    set(value) {
+        if (Object.is(value, this.value))
+            return;
+        this.value = value;
+        this.version++;
+        this.notify();
+    }
+    /** Mark changed without replacing the value (mutated in place). */
+    touch() {
+        this.version++;
+        this.notify();
+    }
+    get observed() {
+        return this.subscribers.size > 0;
+    }
+    subscribe(fn) {
+        if (this.subscribers.size === 0)
+            this.hooks?.observed?.();
+        this.subscribers.add(fn);
+        return () => {
+            if (this.subscribers.delete(fn) && this.subscribers.size === 0)
+                this.hooks?.unobserved?.();
+        };
+    }
+    notify() {
+        for (const fn of this.subscribers) {
+            if (batchDepth > 0)
+                queued.add(fn);
+            else
+                fn();
+        }
+    }
+}
+export function batch(fn) {
+    batchDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        if (--batchDepth === 0) {
+            const run = [...queued];
+            queued.clear();
+            for (const fn of run)
+                fn();
+        }
+    }
+}
+/** Run `fn`, collecting the states it reads (with their versions). */
+export function track(fn) {
+    const previous = tracking;
+    const deps = new Map();
+    tracking = deps;
+    try {
+        return [fn(), deps];
+    }
+    finally {
+        tracking = previous;
+    }
+}
+/** Read without recording dependencies. */
+export function untracked(fn) {
+    const previous = tracking;
+    tracking = null;
+    try {
+        return fn();
+    }
+    finally {
+        tracking = previous;
+    }
+}
+/** A tracked computation with listeners: the engine behind `observer()`. */
+export class Reaction {
+    deps = new Map();
+    unsubscribers = new Map();
+    listeners = new Set();
+    version = 0;
+    /** Run `fn` and make its reads this reaction's dependencies. */
+    track(fn) {
+        const [result, deps] = track(fn);
+        this.deps = deps;
+        if (this.listeners.size > 0)
+            this.sync();
+        return result;
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        if (this.listeners.size === 1) {
+            this.sync();
+            // A dependency changed between tracking and subscribing.
+            for (const [state, seen] of this.deps) {
+                if (state.version !== seen) {
+                    this.changed();
+                    break;
+                }
+            }
+        }
+        return () => {
+            this.listeners.delete(listener);
+            if (this.listeners.size === 0)
+                this.dispose();
+        };
+    };
+    getVersion = () => this.version;
+    dispose() {
+        for (const unsubscribe of this.unsubscribers.values())
+            unsubscribe();
+        this.unsubscribers.clear();
+    }
+    sync() {
+        for (const [state, unsubscribe] of this.unsubscribers) {
+            if (!this.deps.has(state)) {
+                unsubscribe();
+                this.unsubscribers.delete(state);
+            }
+        }
+        for (const state of this.deps.keys()) {
+            if (!this.unsubscribers.has(state))
+                this.unsubscribers.set(state, state.subscribe(this.changed));
+        }
+    }
+    changed = () => {
+        this.version++;
+        for (const listener of [...this.listeners])
+            listener();
+    };
+}
+/** Re-run `fn` whenever what it read changes. Returns a stop function. */
+export function autorun(fn) {
+    const reaction = new Reaction();
+    const run = () => reaction.track(fn);
+    const stop = reaction.subscribe(run);
+    run();
+    return stop;
+}

package/dist/store.d.ts

@@ -0,0 +1,45 @@
+import { State } from "./signal.js";
+import type { WireRecord } from "./protocol.js";
+export type RowStatus = "fresh" | "stale" | "pending" | "failed";
+export type Presence = "none" | "loading" | "loaded" | "missing" | "error";
+export declare class RecordCell {
+    readonly table: string;
+    readonly id: string;
+    readonly fields: Map<string, State<unknown>>;
+    readonly status: State<RowStatus>;
+    readonly presence: State<Presence>;
+    readonly errors: State<Record<string, string>>;
+    /** The server's message when it refused to load this record (`presence` is `error`). */
+    readonly loadError: State<string | null>;
+    /** A reload failed: the next read fetches it again. */
+    reload: boolean;
+    /** Bumps whenever any field changes (for `useRecord`, persistence). */
+    readonly version: State<number>;
+    baseline: Record<string, unknown>;
+    readonly pending: Map<string, unknown>;
+    /** Last time something read this cell; eviction keeps recent ones. */
+    touched: number;
+    constructor(table: string, id: string);
+    field(name: string): State<unknown>;
+    get(name: string): unknown;
+    /** The record as the UI sees it now (pending over baseline). */
+    snapshot(): Record<string, unknown>;
+    /** The server's version arrived. */
+    applyServer(record: WireRecord, status?: RowStatus): void;
+    setPending(patch: Record<string, unknown>): void;
+    /** Drop pending edits for `keys` (confirmed or rejected). */
+    settle(keys: string[], status: RowStatus, errors?: Record<string, string>): void;
+    /** The server refused to load it. */
+    refused(message: string): void;
+    markRemoved(): void;
+    private effective;
+    private refresh;
+}
+export declare class Store {
+    private tables;
+    cell(table: string, id: string): RecordCell;
+    peek(table: string, id: string): RecordCell | undefined;
+    cells(table: string): IterableIterator<RecordCell>;
+    allCells(): RecordCell[];
+    evict(table: string, id: string): void;
+}

package/dist/store.js

@@ -0,0 +1,144 @@
+// The record store: one cell per (table, id).
+//
+// A cell keeps the server's last confirmed record (the baseline) and the
+// local edits in flight (pending). Readers see pending laid over baseline,
+// per field, through one `State` per field — so a component that shows
+// `order.status` re-renders when the status changes and not when the note
+// does. A remote change updates the baseline and the pending edits stay on
+// top (Linear's rebase; the browser twin of Diorama's PendingFlashes).
+import { State, batch } from "./signal.js";
+export class RecordCell {
+    table;
+    id;
+    fields = new Map();
+    status = new State("fresh");
+    presence = new State("none");
+    errors = new State({});
+    /** The server's message when it refused to load this record (`presence` is `error`). */
+    loadError = new State(null);
+    /** A reload failed: the next read fetches it again. */
+    reload = false;
+    /** Bumps whenever any field changes (for `useRecord`, persistence). */
+    version = new State(0);
+    baseline = {};
+    pending = new Map();
+    /** Last time something read this cell; eviction keeps recent ones. */
+    touched = Date.now();
+    constructor(table, id) {
+        this.table = table;
+        this.id = id;
+    }
+    field(name) {
+        let state = this.fields.get(name);
+        if (!state) {
+            state = new State(this.effective(name));
+            this.fields.set(name, state);
+        }
+        return state;
+    }
+    get(name) {
+        this.touched = Date.now();
+        return this.field(name).get();
+    }
+    /** The record as the UI sees it now (pending over baseline). */
+    snapshot() {
+        const out = { ...this.baseline };
+        for (const [k, v] of this.pending)
+            out[k] = v;
+        out.id = this.id;
+        return out;
+    }
+    /** The server's version arrived. */
+    applyServer(record, status = "fresh") {
+        batch(() => {
+            const keys = new Set([...Object.keys(this.baseline), ...Object.keys(record)]);
+            this.baseline = { ...record };
+            for (const key of keys)
+                this.refresh(key);
+            if (this.pending.size === 0)
+                this.status.set(status);
+            this.presence.set("loaded");
+            this.loadError.set(null);
+            this.reload = false;
+            this.version.set(this.version.peek() + 1);
+        });
+    }
+    setPending(patch) {
+        batch(() => {
+            for (const [k, v] of Object.entries(patch)) {
+                this.pending.set(k, v);
+                this.refresh(k);
+            }
+            this.status.set("pending");
+            this.version.set(this.version.peek() + 1);
+        });
+    }
+    /** Drop pending edits for `keys` (confirmed or rejected). */
+    settle(keys, status, errors = {}) {
+        batch(() => {
+            for (const k of keys) {
+                this.pending.delete(k);
+                this.refresh(k);
+            }
+            if (this.pending.size === 0)
+                this.status.set(status);
+            this.errors.set(errors);
+            this.version.set(this.version.peek() + 1);
+        });
+    }
+    /** The server refused to load it. */
+    refused(message) {
+        batch(() => {
+            this.loadError.set(message);
+            this.presence.set("error");
+        });
+    }
+    markRemoved() {
+        batch(() => {
+            this.baseline = {};
+            this.pending.clear();
+            for (const key of this.fields.keys())
+                this.refresh(key);
+            this.presence.set("missing");
+            this.version.set(this.version.peek() + 1);
+        });
+    }
+    effective(name) {
+        if (name === "id")
+            return this.id;
+        return this.pending.has(name) ? this.pending.get(name) : (this.baseline[name] ?? null);
+    }
+    refresh(name) {
+        const state = this.fields.get(name);
+        if (state)
+            state.set(this.effective(name));
+    }
+}
+export class Store {
+    tables = new Map();
+    cell(table, id) {
+        let cells = this.tables.get(table);
+        if (!cells) {
+            cells = new Map();
+            this.tables.set(table, cells);
+        }
+        let cell = cells.get(id);
+        if (!cell) {
+            cell = new RecordCell(table, id);
+            cells.set(id, cell);
+        }
+        return cell;
+    }
+    peek(table, id) {
+        return this.tables.get(table)?.get(id);
+    }
+    cells(table) {
+        return (this.tables.get(table) ?? new Map()).values();
+    }
+    allCells() {
+        return [...this.tables.values()].flatMap((m) => [...m.values()]);
+    }
+    evict(table, id) {
+        this.tables.get(table)?.delete(id);
+    }
+}

package/dist/table.d.ts

@@ -0,0 +1,62 @@
+import type { Vantage } from "./client.js";
+import type { AnyModel } from "./model.js";
+import type { Where } from "./protocol.js";
+import type { RunFactory, RunTypes } from "./run/types.js";
+import type { ActionResult, LazyCollection, LazyReference, SchemaTypes, TableMeta } from "./types.js";
+type ModelsOf<S extends SchemaTypes> = S["models"];
+export type TableName<S extends SchemaTypes> = keyof ModelsOf<S> & string;
+export type ModelOf<S extends SchemaTypes, T> = T extends keyof ModelsOf<S> ? ModelsOf<S>[T] : never;
+export type InputOf<S extends SchemaTypes, T> = T extends keyof S["inputs"] ? S["inputs"][T] : never;
+type ArgsFor<I> = {} extends I ? [input?: I] : [input: I];
+export type TableActionsOf<S extends SchemaTypes, T> = T extends keyof S["tableActions"] ? {
+    [A in keyof S["tableActions"][T]]: (...input: ArgsFor<S["tableActions"][T][A]>) => Promise<ActionResult<undefined>>;
+} : {};
+/** `db.run`: a run factory per project action. */
+export type ProjectActions<S extends SchemaTypes> = {
+    [A in keyof S["projectActions"]]: RunFactory<S["projectActions"][A] extends RunTypes ? S["projectActions"][A] : RunTypes>;
+};
+export interface TableHandle<M, I, A> {
+    readonly name: string;
+    readonly meta: TableMeta;
+    /** The whole table (as far as your scope goes). */
+    readonly all: LazyCollection<M>;
+    /** The record if it's loaded; reading starts loading it. */
+    get(id: string): M | undefined;
+    ref(id: string): LazyReference<M>;
+    where(conditions: Partial<Record<string, unknown>> | Where[]): LazyCollection<M>;
+    sort(column: string, direction?: "asc" | "desc"): LazyCollection<M>;
+    search(text: string): LazyCollection<M>;
+    create(input: I): Promise<ActionResult<M>>;
+    /** Toolbar actions of the table's pages. */
+    readonly actions: A;
+}
+export type Tables<S extends SchemaTypes> = {
+    readonly [T in TableName<S>]: TableHandle<ModelOf<S, T>, InputOf<S, T>, TableActionsOf<S, T>>;
+};
+export declare class Table implements TableHandle<AnyModel, Record<string, unknown>, Record<string, unknown>> {
+    private db;
+    readonly name: string;
+    readonly meta: TableMeta;
+    readonly actions: Record<string, unknown>;
+    constructor(db: Vantage<any>, name: string, meta: TableMeta);
+    get all(): LazyCollection<AnyModel>;
+    get(id: string): AnyModel | undefined;
+    ref(id: string): LazyReference<AnyModel>;
+    where(conditions: Partial<Record<string, unknown>> | Where[]): LazyCollection<AnyModel>;
+    sort(column: string, direction?: "asc" | "desc"): LazyCollection<AnyModel>;
+    search(text: string): LazyCollection<AnyModel>;
+    create(input: Record<string, unknown>): Promise<ActionResult<AnyModel>>;
+}
+export declare class Reference implements LazyReference<AnyModel> {
+    private db;
+    private table;
+    private idFn;
+    constructor(db: Vantage<any>, table: string, idFn: () => string | null);
+    get id(): string | null;
+    get value(): AnyModel | undefined;
+    get status(): import("./store.js").Presence;
+    get error(): string | null;
+    load(): Promise<AnyModel | undefined>;
+    then<A = AnyModel | undefined, B = never>(onfulfilled?: ((value: AnyModel | undefined) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): PromiseLike<A | B>;
+}
+export {};

package/dist/table.js

@@ -0,0 +1,82 @@
+// The typed table API: `db.order.where(…)`, `db.order.ref(id)`, and the
+// references that point at one record.
+import { toColumns } from "./util.js";
+export class Table {
+    db;
+    name;
+    meta;
+    actions;
+    constructor(db, name, meta) {
+        this.db = db;
+        this.name = name;
+        this.meta = meta;
+        this.actions = new Proxy({}, { get: (_, action) => (input) => db.invoke(`${name}.${action}`, undefined, input ?? {}) });
+    }
+    get all() {
+        return this.db.collection({ table: this.name });
+    }
+    get(id) {
+        return this.ref(id).value;
+    }
+    ref(id) {
+        return this.db.ref(this.name, () => id);
+    }
+    where(conditions) {
+        return this.all.where(conditions);
+    }
+    sort(column, direction = "asc") {
+        return this.all.sort(column, direction);
+    }
+    search(text) {
+        return this.all.search(text);
+    }
+    create(input) {
+        return this.db.write(this.name, undefined, toColumns(this.meta, input));
+    }
+}
+export class Reference {
+    db;
+    table;
+    idFn;
+    constructor(db, table, idFn) {
+        this.db = db;
+        this.table = table;
+        this.idFn = idFn;
+    }
+    get id() {
+        return this.idFn();
+    }
+    get value() {
+        const id = this.id;
+        if (!id)
+            return undefined;
+        const cell = this.db.store.cell(this.table, id);
+        cell.touched = Date.now();
+        const presence = cell.presence.get();
+        if (presence === "none")
+            void this.db.requestRecords(this.table, [id]);
+        if (presence === "loaded" && cell.reload) {
+            cell.reload = false;
+            void this.db.reloadRecords(this.table, [id]);
+        }
+        return presence === "loaded" ? this.db.model(this.table, id) : undefined;
+    }
+    get status() {
+        const id = this.id;
+        return id ? this.db.store.cell(this.table, id).presence.get() : "none";
+    }
+    get error() {
+        const id = this.id;
+        return id ? this.db.store.cell(this.table, id).loadError.get() : null;
+    }
+    async load() {
+        const id = this.id;
+        if (!id)
+            return undefined;
+        await this.db.requestRecords(this.table, [id]);
+        return this.db.store.cell(this.table, id).presence.peek() === "loaded" ? this.db.model(this.table, id) : undefined;
+    }
+    then(onfulfilled, onrejected) {
+        return this.load().then(onfulfilled, onrejected);
+    }
+}