@vantage-ui/client 0.0.0-stage → 0.4.4

package/dist/client.js

@@ -0,0 +1,61 @@
+// The client: a typed, reactive object graph over a vantage-server.
+//
+// `Vantage` is built in layers, each in its own file:
+//   client-core.ts        state, request routing, status, persistence, models
+//   client-loading.ts     records by id, collections and windows, the sweep
+//   client-writes.ts      optimistic writes, undo
+//   client-runs.ts        action runs: factories, followed runs, `run` frames
+//   client-connection.ts  hello, reconnect, resync, server-pushed frames
+import { ClientConnection } from "./client-connection.js";
+import { Collection } from "./collection.js";
+import { specKey } from "./collection-cell.js";
+import { Reference, Table } from "./table.js";
+export function createVantage(options) {
+    const db = new Vantage(options);
+    return new Proxy(db, {
+        get(target, prop, receiver) {
+            if (typeof prop === "string" && !(prop in target) && prop in options.schema.tables)
+                return target.table(prop);
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+export class Vantage extends ClientConnection {
+    /** `db.run.magic_promotion.start({ bakery })`: project actions, as runs. */
+    run;
+    constructor(options) {
+        super(options);
+        this.run = new Proxy({}, {
+            get: (_, action) => (typeof action === "string" ? this.runs(action) : undefined),
+        });
+        this.sweeper = setInterval(() => this.sweep(), 5_000);
+        void this.start();
+    }
+    table(name) {
+        let handle = this.handles.get(name);
+        if (!handle) {
+            handle = new Table(this, name, this.meta(name));
+            this.handles.set(name, handle);
+        }
+        return handle;
+    }
+    /** @internal */ ref(table, id) {
+        return new Reference(this, table, id);
+    }
+    /** @internal The collection `spec` describes: the same object for the same description while anything reads it. */
+    collection(spec) {
+        const key = specKey(spec);
+        let collection = this.interned.get(key);
+        if (!collection) {
+            collection = new Collection(this, spec);
+            this.interned.set(key, collection);
+        }
+        return collection;
+    }
+    /** Run loads ahead of navigation; resolves when they're done. */
+    async preload(fn) {
+        const result = fn();
+        const items = Array.isArray(result) ? result : [result];
+        await Promise.all(items.map((r) => (r && typeof r.then === "function" ? r : r && typeof r.load === "function" ? r.load() : r)));
+    }
+}

package/dist/codegen/cli.d.ts

@@ -0,0 +1,8 @@
+/** Run the CLI; the exit code. Messages go to `log` and `fail`, one line each. */
+export declare function main(args: string[], log?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}, fail?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}): Promise<number>;

package/dist/codegen/cli.js

@@ -0,0 +1,54 @@
+// `vantage-client generate --from <url-or-file> --out <file>`.
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { emit } from "./emit.js";
+import { loadSchema } from "./fetch.js";
+import { GenerateError } from "./schema.js";
+const USAGE = "usage: vantage-client generate --from <url-to-/v1/schema | schema.json> --out <file>";
+/** Run the CLI; the exit code. Messages go to `log` and `fail`, one line each. */
+export async function main(args, log = console.log, fail = console.error) {
+    const [command, ...rest] = args;
+    if (command !== "generate") {
+        fail(USAGE);
+        return 1;
+    }
+    try {
+        const from = option(rest, "--from");
+        const out = option(rest, "--out");
+        if (!from || !out) {
+            fail(USAGE);
+            return 1;
+        }
+        const schema = await loadSchema(from);
+        await write(out, emit(schema, from));
+        log(`wrote ${out} (schema ${schema.hash})`);
+        return 0;
+    }
+    catch (e) {
+        if (!(e instanceof GenerateError))
+            throw e;
+        fail(`vantage-client: ${e.message}`);
+        return 1;
+    }
+}
+/** The value after `name`; undefined when `name` isn't given. */
+function option(args, name) {
+    const at = args.indexOf(name);
+    if (at < 0)
+        return undefined;
+    const value = args[at + 1];
+    if (value === undefined || value.startsWith("--"))
+        throw new GenerateError(`${name} needs a value`);
+    return value;
+}
+/** Write `text` to `path`, creating its directory when missing. */
+async function write(path, text) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, text);
+    }
+    catch (e) {
+        const code = e.code ?? (e instanceof Error ? e.message : String(e));
+        throw new GenerateError(`cannot write ${path}: ${code}`);
+    }
+}

package/dist/codegen/emit.d.ts

@@ -0,0 +1,3 @@
+import { type ServerSchema } from "./schema.js";
+/** Throws a `GenerateError` when an entity member takes a name the model reserves. */
+export declare function emit(schema: ServerSchema, source: string): string;

package/dist/codegen/emit.js

@@ -0,0 +1,190 @@
+// `generate`: TypeScript for one API, from its `/v1/schema`.
+//
+// Per table it writes:
+// - `XFields`: the record as data (what a draft edits);
+// - `XInput`: what `create()` takes (mandatory columns required);
+// - `X`: the model the app reads. Reference columns become
+//   `LazyReference`s, `has_many` references `LazyCollection`s, and
+//   row actions become methods and `$run` factories;
+// - `X<Action>Run`: a row action's run types (args, state, inputs, messages).
+//
+// plus `<Action>Run` per project action, `Schema` (types) and `schema`
+// (runtime metadata the client builds models from). Everything comes out in the schema's own order (the API's
+// and the YAML's), so the same schema always gives the same file.
+import { pascal } from "../util.js";
+import { fieldMeta, metaTable, required, runMeta } from "./meta.js";
+import { RunNames, runInterface } from "./runs.js";
+import { refuseReservedNames } from "./schema.js";
+const stringify = (value) => JSON.stringify(value ?? null);
+/** Schema text inside a generated comment: it can neither close the comment nor break the line. */
+const doc = (text) => String(text ?? "").replace(/\*\//g, "*\\/").replace(/[^\S ]+/g, " ");
+/** Throws a `GenerateError` when an entity member takes a name the model reserves. */
+export function emit(schema, source) {
+    refuseReservedNames(schema);
+    const hash = typeof schema.hash === "string" ? schema.hash : "";
+    let out = "";
+    const line = (text = "") => (out += text + "\n");
+    line(`// Generated by @vantage-ui/client generate from ${doc(source)} (schema ${doc(hash)}). Never edit by hand.`);
+    line("// When the API changes, the Vantage web dev container regenerates it from schema.json;");
+    line("// elsewhere, run `npx vantage-client generate --from <api>/v1/schema` again.\n");
+    // Only the types the file uses, so it passes `noUnusedLocals`.
+    const tables = schema.tables ?? [];
+    const rowActionsAnywhere = tables.some((t) => (t.actions ?? []).some((a) => a.per_row === true));
+    const used = [
+        ["ActionResult", rowActionsAnywhere],
+        ["LazyCollection", tables.some((t) => (t.has_many ?? []).length > 0)],
+        ["LazyReference", tables.some((t) => (t.references ?? []).length > 0)],
+        ["Model", tables.length > 0],
+        ["RunFactory", rowActionsAnywhere],
+    ];
+    const types = used.filter(([, uses]) => uses).map(([name]) => name);
+    if (types.length > 0)
+        line(`import type { ${types.join(", ")} } from "@vantage-ui/client";\n`);
+    const models = [];
+    const fields = [];
+    const inputs = [];
+    const tableActions = [];
+    const metaTables = {};
+    const runNames = new RunNames([
+        ...tables.flatMap((t) => ["", "Fields", "Input", "Action"].map((suffix) => `${pascal(t.name ?? "")}${suffix}`)),
+        ...["Models", "Fields", "Inputs", "TableActions", "Schema", "ProjectActions"],
+    ]);
+    for (const raw of tables) {
+        const table = { ...raw, columns: raw.columns ?? [], references: raw.references ?? [], has_many: raw.has_many ?? [], actions: raw.actions ?? [] };
+        const name = table.name ?? "";
+        const ty = pascal(name);
+        const readOnly = table.read_only === true;
+        const rowActions = table.actions.filter((a) => a.per_row === true);
+        const toolbar = table.actions.filter((a) => a.per_row !== true);
+        // --- fields (data)
+        line(`/** \`${doc(typeof table.key === "string" ? table.key : name)}\` as data${readOnly ? " (read-only)" : ""} */`);
+        line(`export interface ${ty}Fields {`);
+        line("  readonly id: string;");
+        for (const c of table.columns.filter((c) => c.name !== "id" && c.hidden !== true)) {
+            const ro = readOnly || c.readonly === true;
+            if (typeof c.label === "string")
+                line(`  /** ${doc(c.label)} */`);
+            line(`  ${ro ? "readonly " : ""}${key(c.name ?? "")}: ${columnType(c)} | null;`);
+        }
+        line("}\n");
+        // --- create input
+        if (!readOnly) {
+            line(`export interface ${ty}Input {`);
+            line(`  /** Optional client-made id (\`${doc(name)}:<uuid>\` or bare); the server makes one otherwise. */`);
+            line("  id?: string;");
+            for (const c of table.columns.filter((c) => c.name !== "id" && c.readonly !== true)) {
+                const req = c.mandatory === true;
+                line(`  ${key(c.name ?? "")}${req ? "" : "?"}: ${columnType(c)}${req ? "" : " | null"};`);
+            }
+            line("}\n");
+            inputs.push(`  ${key(name)}: ${ty}Input;`);
+        }
+        else {
+            inputs.push(`  ${key(name)}: never;`);
+        }
+        // --- model
+        const relColumns = table.references.map((r) => r.column).filter((c) => typeof c === "string" && table.references.some((r) => r.name === c));
+        const omit = relColumns.length === 0 ? `${ty}Fields` : `Omit<${ty}Fields, ${relColumns.map(stringify).join(" | ")}>`;
+        line(`export interface ${ty} extends Model<${stringify(name)}, ${ty}Fields>, Readonly<${omit}> {`);
+        for (const r of table.references) {
+            line(`  /** \`${doc(r.column)}\` → ${doc(r.table)} */`);
+            line(`  readonly ${key(r.name ?? "")}: LazyReference<${pascal(r.table ?? "")}>;`);
+        }
+        for (const h of table.has_many)
+            line(`  readonly ${key(h.name ?? "")}: LazyCollection<${pascal(h.table ?? "")}>;`);
+        line("  /** Row actions whose `when:` holds right now (decided by the server). */");
+        line(`  readonly $actions: readonly ${rowActions.length === 0 ? "never" : `${ty}Action`}[];`);
+        for (const a of rowActions) {
+            const input = fieldsType(a.fields);
+            const arg = input === "{}" ? "" : inputOptional(a.fields) ? `input?: ${input}` : `input: ${input}`;
+            line(`  /** ${doc(a.label)}: a run, awaited to its end */`);
+            line(`  ${key(a.name ?? "")}(${arg}): Promise<ActionResult<${ty}>>;`);
+        }
+        const rowRuns = rowActions.map((a) => runNames.take(`${ty}${pascal(a.name ?? "")}`));
+        if (rowActions.length > 0) {
+            line("  /** The row actions as runs: `start`, `attach`, live `state` and messages. */");
+            line(`  readonly $run: { ${rowActions.map((a, i) => `${key(a.name ?? "")}: RunFactory<${rowRuns[i]}>`).join("; ")} };`);
+        }
+        line("}\n");
+        if (rowActions.length > 0)
+            line(`export type ${ty}Action = ${rowActions.map((a) => stringify(a.name ?? "")).join(" | ")};\n`);
+        rowActions.forEach((a, i) => line(runInterface(rowRuns[i], fieldsType(a.fields), a, key)));
+        const entries = toolbar.map((a) => `    /** ${doc(a.label)} */\n    ${key(a.name ?? "")}: ${fieldsType(a.fields)};`);
+        tableActions.push(`  ${key(name)}: {\n${entries.join("\n")}\n  };`);
+        models.push(`  ${key(name)}: ${ty};`);
+        fields.push(`  ${key(name)}: ${ty}Fields;`);
+        metaTables[name] = metaTable(table);
+    }
+    const projectActions = [];
+    const metaActions = {};
+    for (const action of schema.actions ?? []) {
+        const name = action.name ?? "";
+        const title = typeof action.title === "string" ? action.title : typeof action.key === "string" ? action.key : "";
+        const kind = typeof action.kind === "string" ? action.kind : "";
+        let args;
+        if (kind === "http_request") {
+            const params = (action.params ?? []).filter((p) => typeof p === "string").map((p) => `${key(p)}: string`);
+            args = params.length === 0 ? "{}" : `{ ${params.join("; ")} }`;
+        }
+        else
+            args = fieldsType(action.fields);
+        const run = runNames.take(pascal(name));
+        line(`/** ${doc(title)}${kind ? ` (${doc(kind)})` : ""} */`);
+        line(runInterface(run, args, action, key));
+        projectActions.push(`  ${key(name)}: ${run};`);
+        metaActions[name] = { key: action.key ?? null, kind: action.kind ?? null, fields: fieldMeta(action.fields), ...runMeta(action) };
+    }
+    line("/** Project actions (`action/*.yaml`) a client can run: `db.run.<name>.start(args)`. */");
+    line(projectActions.length ? `export interface ProjectActions {\n${projectActions.join("\n")}\n}\n` : "export interface ProjectActions {}\n");
+    line(`export interface Models {\n${models.join("\n")}\n}\n`);
+    line(`export interface Fields {\n${fields.join("\n")}\n}\n`);
+    line(`export interface Inputs {\n${inputs.join("\n")}\n}\n`);
+    line(`export interface TableActions {\n${tableActions.join("\n")}\n}\n`);
+    line("export interface Schema {\n  models: Models;\n  fields: Fields;\n  inputs: Inputs;\n  tableActions: TableActions;\n  projectActions: ProjectActions;\n}\n");
+    line("/** Runtime metadata `createVantage({ schema })` builds models from. */");
+    line(`export const schema = ${JSON.stringify({ hash, tables: metaTables, actions: metaActions }, null, 2)} as const;`);
+    return out;
+}
+function columnType(column) {
+    if (Array.isArray(column.enum) && column.enum.length > 0)
+        return column.enum.map(stringify).join(" | ");
+    switch (typeof column.type === "string" ? column.type : "string") {
+        case "int":
+        case "float":
+            return "number";
+        // Exact: a string on the wire, so pence never become 0.30000000000000004.
+        case "decimal":
+            return "number | string";
+        case "bool":
+            return "boolean";
+        // date, time, timestamp, datetime, duration: ISO strings on the wire.
+        default:
+            return "string";
+    }
+}
+function inputOptional(fields) {
+    return (fields ?? []).every((f) => !required(f));
+}
+function fieldsType(list) {
+    const fields = list ?? [];
+    if (fields.length === 0)
+        return "{}";
+    const parts = fields.map((f) => {
+        let ty;
+        if (Array.isArray(f.choices) && f.widget !== "checklist")
+            ty = f.choices.map(stringify).join(" | ");
+        else if (f.type === "int" || f.type === "float" || f.type === "decimal")
+            ty = "number";
+        else if (f.type === "bool")
+            ty = "boolean";
+        else
+            ty = "string";
+        return `${key(f.name ?? "")}${required(f) ? "" : "?"}: ${ty}`;
+    });
+    return `{ ${parts.join("; ")} }`;
+}
+/** A property name: bare when it is an identifier, quoted otherwise. */
+function key(name) {
+    const plain = name !== "" && /^[A-Za-z0-9_$]+$/.test(name) && !/^[0-9]/.test(name);
+    return plain ? name : stringify(name);
+}

package/dist/codegen/fetch.d.ts

@@ -0,0 +1,4 @@
+import { type ServerSchema } from "./schema.js";
+export declare function loadSchema(from: string): Promise<ServerSchema & {
+    hash: string;
+}>;

package/dist/codegen/fetch.js

@@ -0,0 +1,41 @@
+// Where `generate --from` reads the schema: an `http(s)://` URL (usually a
+// server's `/v1/schema`), or anything else as a path to a JSON file.
+import { readFile } from "node:fs/promises";
+import { GenerateError, isSchema } from "./schema.js";
+export async function loadSchema(from) {
+    const text = /^https?:\/\//i.test(from) ? await fetchText(from) : await readText(from);
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new GenerateError(`not a schema: ${from} did not return JSON`);
+    }
+    if (!isSchema(body))
+        throw new GenerateError(`not a schema: ${from} has no \`tables\` list`);
+    return { ...body, hash: typeof body.hash === "string" ? body.hash : "" };
+}
+async function fetchText(url) {
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (e) {
+        throw new GenerateError(`cannot reach ${url}: ${reason(e)}`);
+    }
+    if (!response.ok)
+        throw new GenerateError(`cannot reach ${url}: HTTP ${response.status}`);
+    return response.text();
+}
+async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (e) {
+        throw new GenerateError(`cannot read ${path}: ${reason(e)}`);
+    }
+}
+function reason(e) {
+    const cause = e.cause;
+    return cause?.code ?? cause?.message ?? (e instanceof Error ? e.message : String(e));
+}

package/dist/codegen/meta.d.ts

@@ -0,0 +1,13 @@
+import type { ServerField, ServerMessage, ServerStateVar, ServerTable } from "./schema.js";
+type Meta = Record<string, unknown>;
+export declare function metaTable(table: ServerTable): Meta;
+/** A run's variables (type, starting value, whether the client writes it) and message names. */
+export declare function runMeta(action: {
+    state?: ServerStateVar[] | null;
+    messages?: ServerMessage[] | null;
+}): Meta;
+/** What a client form needs to render a field. */
+export declare function fieldMeta(fields: ServerField[] | undefined | null): Meta[];
+/** Required unless it says `required: false` or has a default. */
+export declare function required(f: ServerField): boolean;
+export {};

package/dist/codegen/meta.js

@@ -0,0 +1,59 @@
+// The runtime metadata (`export const schema = …`) a generated file carries:
+// per table its load policy, the API's sort and filter whitelists, columns
+// (with enum values), references, has-many and actions, and the project
+// actions, in the shape `createVantage({ schema })` reads.
+const or = (value) => value ?? null;
+export function metaTable(table) {
+    const columns = Object.fromEntries((table.columns ?? []).map((c) => [
+        String(c.name ?? ""),
+        {
+            type: or(c.type),
+            ...(c.readonly === true && { readonly: true }),
+            ...(c.hidden === true && { hidden: true }),
+            ...(Array.isArray(c.enum) && c.enum.length > 0 && { enum: c.enum }),
+        },
+    ]));
+    const references = Object.fromEntries((table.references ?? []).map((r) => [String(r.name ?? ""), { column: or(r.column), table: or(r.table) }]));
+    const hasMany = Object.fromEntries((table.has_many ?? []).map((h) => [String(h.name ?? ""), { table: or(h.table), foreignKey: or(h.foreign_key) }]));
+    const actions = Object.fromEntries((table.actions ?? []).map((a) => [String(a.name ?? ""), { perRow: a.per_row === true, label: or(a.label), fields: fieldMeta(a.fields), ...runMeta(a) }]));
+    return {
+        key: or(table.key),
+        load: or(table.load),
+        persist: or(table.persist),
+        live: or(table.live),
+        readOnly: or(table.read_only),
+        idColumn: or(table.id_column),
+        title: or(table.title),
+        collectionLimit: or(table.collection_limit),
+        // The API's whitelists: what a collection may sort and filter by, and its default sort.
+        sortable: or(table.sortable),
+        filter: or(table.filter),
+        defaultSort: or(table.default_sort),
+        columns,
+        references,
+        hasMany,
+        actions,
+    };
+}
+/** A run's variables (type, starting value, whether the client writes it) and message names. */
+export function runMeta(action) {
+    const state = Object.fromEntries((action.state ?? []).map((v) => [String(v.name ?? ""), { type: typeof v.type === "string" ? v.type : "any", default: or(v.default), input: v.input === true }]));
+    return { state, messages: (action.messages ?? []).map((m) => String(m.name ?? "")) };
+}
+/** What a client form needs to render a field. */
+export function fieldMeta(fields) {
+    return (fields ?? []).map((f) => ({
+        name: or(f.name),
+        type: typeof f.type === "string" ? f.type : "string",
+        label: or(f.label),
+        required: required(f),
+        choices: or(f.choices),
+        default: or(f.default),
+        widget: or(f.widget),
+        options: f.options != null,
+    }));
+}
+/** Required unless it says `required: false` or has a default. */
+export function required(f) {
+    return (typeof f.required === "boolean" ? f.required : true) && f.default == null;
+}

package/dist/codegen/runs.d.ts

@@ -0,0 +1,20 @@
+import type { ServerMessage, ServerStateVar } from "./schema.js";
+/**
+ * Hands out run type names (`<Base>Run`) that are valid identifiers and
+ * clash with nothing else in the file: a base starting with a digit gets
+ * `_`, an empty one (a name with no ASCII letters) becomes `Action`, and a
+ * taken name gets `2`, `3`, … in the order names are asked for.
+ */
+export declare class RunNames {
+    private used;
+    constructor(taken: Iterable<string>);
+    take(base: string): string;
+}
+/**
+ * `export interface <name> { args; state; inputs; messages }` for an action
+ * that takes `args` (a type) and declares `state` and `messages`.
+ */
+export declare function runInterface(name: string, args: string, action: {
+    state?: ServerStateVar[] | null;
+    messages?: ServerMessage[] | null;
+}, key: (name: string) => string): string;

package/dist/codegen/runs.js

@@ -0,0 +1,58 @@
+// The run types of one action: what `start` takes (`args`), the shared
+// variables (`state`), the ones a client may write (`inputs`) and the
+// messages (`messages`), as one interface the client's `Run<T>` reads.
+/** A run variable's or message field's type (`int`, `list`, …) in TypeScript. */
+function typeOf(type) {
+    switch (type) {
+        case "string":
+            return "string";
+        case "int":
+        case "float":
+            return "number";
+        case "bool":
+            return "boolean";
+        case "list":
+            return "unknown[]";
+        case "map":
+            return "Record<string, unknown>";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Hands out run type names (`<Base>Run`) that are valid identifiers and
+ * clash with nothing else in the file: a base starting with a digit gets
+ * `_`, an empty one (a name with no ASCII letters) becomes `Action`, and a
+ * taken name gets `2`, `3`, … in the order names are asked for.
+ */
+export class RunNames {
+    used;
+    constructor(taken) {
+        this.used = new Set(taken);
+    }
+    take(base) {
+        const root = `${base === "" ? "Action" : /^[0-9]/.test(base) ? `_${base}` : base}Run`;
+        let name = root;
+        for (let n = 2; this.used.has(name); n++)
+            name = `${root}${n}`;
+        this.used.add(name);
+        return name;
+    }
+}
+/**
+ * `export interface <name> { args; state; inputs; messages }` for an action
+ * that takes `args` (a type) and declares `state` and `messages`.
+ */
+export function runInterface(name, args, action, key) {
+    const vars = action.state ?? [];
+    const object = (parts) => (parts.length === 0 ? "{}" : `{ ${parts.join("; ")} }`);
+    const variable = (v) => `${key(v.name ?? "")}: ${typeOf(v.type)}`;
+    const state = object(vars.map(variable));
+    const inputs = object(vars.filter((v) => v.input === true).map(variable));
+    const messages = object((action.messages ?? []).map((m) => {
+        const fields = Object.entries(m.fields ?? {}).map(([field, type]) => `${key(field)}: ${typeOf(type)}`);
+        // A message without fields may be sent with no payload at all (`emit("done")`).
+        return `${key(m.name ?? "")}: ${fields.length === 0 ? "Record<string, never> | null" : object(fields)}`;
+    }));
+    return `export interface ${name} {\n  args: ${args};\n  state: ${state};\n  inputs: ${inputs};\n  messages: ${messages};\n}\n`;
+}

package/dist/codegen/schema.d.ts

@@ -0,0 +1,97 @@
+import type { Json } from "../protocol.js";
+/** A one-line reason `generate` stops; the CLI prints it and exits 1. */
+export declare class GenerateError extends Error {
+}
+export interface ServerColumn {
+    name?: string;
+    type?: string;
+    enum?: Json[] | null;
+    label?: string | null;
+    hidden?: boolean;
+    readonly?: boolean;
+    mandatory?: boolean;
+    [key: string]: unknown;
+}
+export interface ServerField {
+    name?: string;
+    type?: string;
+    label?: string | null;
+    required?: boolean;
+    choices?: Json[] | null;
+    default?: Json;
+    widget?: string | null;
+    options?: Json;
+    [key: string]: unknown;
+}
+/** A run's shared variable. */
+export interface ServerStateVar {
+    name?: string;
+    type?: string;
+    default?: Json;
+    input?: boolean;
+}
+/** A message a run may send, with its payload fields' types. */
+export interface ServerMessage {
+    name?: string;
+    fields?: Record<string, string> | null;
+}
+export interface ServerTableAction {
+    name?: string;
+    label?: string | null;
+    per_row?: boolean;
+    fields?: ServerField[] | null;
+    state?: ServerStateVar[] | null;
+    messages?: ServerMessage[] | null;
+    [key: string]: unknown;
+}
+export interface ServerTable {
+    name?: string;
+    key?: string;
+    load?: string;
+    persist?: boolean;
+    live?: Json;
+    read_only?: boolean;
+    id_column?: string;
+    title?: string | null;
+    collection_limit?: number;
+    sortable?: string[] | null;
+    filter?: string[] | null;
+    default_sort?: {
+        column: string;
+        direction: "asc" | "desc";
+    } | null;
+    columns?: ServerColumn[] | null;
+    references?: {
+        name?: string;
+        column?: string;
+        table?: string;
+    }[] | null;
+    has_many?: {
+        name?: string;
+        table?: string;
+        foreign_key?: string;
+    }[] | null;
+    actions?: ServerTableAction[] | null;
+    [key: string]: unknown;
+}
+export interface ServerAction {
+    name?: string;
+    key?: string;
+    kind?: string;
+    title?: string | null;
+    fields?: ServerField[] | null;
+    params?: Json[] | null;
+    state?: ServerStateVar[] | null;
+    messages?: ServerMessage[] | null;
+    [key: string]: unknown;
+}
+export interface ServerSchema {
+    hash?: string;
+    tables?: ServerTable[] | null;
+    actions?: ServerAction[] | null;
+    [key: string]: unknown;
+}
+/** Refuse the first entity member that takes a name the model reserves. */
+export declare function refuseReservedNames(schema: ServerSchema): void;
+/** Whether `value` looks like a schema at all: an object with a `tables` array. */
+export declare function isSchema(value: unknown): value is ServerSchema;

package/dist/codegen/schema.js

@@ -0,0 +1,23 @@
+// The shape of `/v1/schema` as far as code generation reads it. Every
+// field is optional: the emitter treats a missing one like the server's
+// default.
+import { reservedClash } from "../reserved.js";
+/** A one-line reason `generate` stops; the CLI prints it and exits 1. */
+export class GenerateError extends Error {
+}
+/** Refuse the first entity member that takes a name the model reserves. */
+export function refuseReservedNames(schema) {
+    for (const table of schema.tables ?? []) {
+        const clash = reservedClash(table.name ?? "", [
+            ...(table.columns ?? []).filter((c) => c.name !== "id" && c.hidden !== true).map((c) => ({ kind: "column", name: c.name ?? "" })),
+            ...[...(table.references ?? []), ...(table.has_many ?? [])].map((r) => ({ kind: "reference", name: r.name ?? "" })),
+            ...(table.actions ?? []).filter((a) => a.per_row === true).map((a) => ({ kind: "action", name: a.name ?? "" })),
+        ]);
+        if (clash)
+            throw new GenerateError(clash);
+    }
+}
+/** Whether `value` looks like a schema at all: an object with a `tables` array. */
+export function isSchema(value) {
+    return value !== null && typeof value === "object" && Array.isArray(value.tables);
+}