@sincpro/web-framework 0.0.0-stage → 0.1.0

package/dist/core/entity.d.ts

@@ -0,0 +1,79 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import type { Method } from "./transport.js";
+/**
+ * Everything a screen needs to know about where an entity lives on the server, declared once.
+ *
+ * Context: a screen should not know a URL. It names the entity, and the entity says where its
+ * list is, where one record is, which Commands it takes, how it is saved and previewed, where a
+ * draft is kept and where its history is. `key` is how the workspace refers to it
+ * (`domain:kind`, the shape of a composer `ResourceRef`).
+ *
+ * The routes are declared, not guessed: sincpro_framework publishes a route per use case and
+ * its model definition does not list them (yet). A route is `"METHOD /path/{id}"` for a write.
+ *
+ *     export const invoices = entity<Invoice>("billing:invoice", {
+ *       list: "/invoices",
+ *       save: "PUT /invoices/{id}",
+ *       preview: "POST /invoices/preview",
+ *       commands: { confirm: "POST /invoices/{id}/confirm", cancel: "POST /invoices/{id}/cancel" },
+ *       history: { route: "/billing-events", type: "Invoice" },
+ *     });
+ */
+export type Entity<T extends AnyRecord = AnyRecord> = {
+    /** `domain:kind`, e.g. `"billing:invoice"`. */
+    key: string;
+    domain: string;
+    kind: string;
+    /** Where the workspace finds it: the list without an id, one record with it — the shape of a
+     *  composer `ResourceRef`, built here so no screen writes `{ domain, kind, id }` by hand. */
+    ref: (id?: string) => EntityRef;
+    /** The route of its list. */
+    list: string;
+    /** The route of one record. */
+    one: (id: string) => string;
+    /** Its Commands, by name. */
+    commands: Readonly<Record<string, WriteRoute>>;
+    /** How an edit is saved: the record's own route with `{id}`. */
+    save?: WriteRoute;
+    /** «What does this record become?» before saving — sincpro_framework's `Preview`. */
+    preview?: WriteRoute;
+    /** Where this caller keeps an edit between requests — sincpro_framework's `Drafts`. */
+    draft?: WriteRoute;
+    /** Its business events: the context's events route, and the `entity_type` they carry. */
+    history?: {
+        route: string;
+        type: string;
+    };
+    /** Only carries the record type; never read. */
+    readonly _record?: T;
+};
+/** A composer `ResourceRef`, structurally: `core/` does not import the composer. */
+export type EntityRef = {
+    domain: string;
+    kind: string;
+    id?: string;
+};
+/** A write: its method and its path, `{id}` where the record's key goes. */
+export type WriteRoute = {
+    method: Method;
+    path: string;
+};
+export type EntityRoutes = {
+    list: string;
+    /** With `{id}` where the key goes. Without it, `<list>/<id>` — sincpro_framework's convention. */
+    one?: string;
+    /** `"POST /invoices/{id}/confirm"`, by name. */
+    commands?: Readonly<Record<string, string>>;
+    save?: string;
+    preview?: string;
+    draft?: string;
+    history?: {
+        route: string;
+        type: string;
+    };
+};
+/** `"POST /invoices/{id}/confirm"` → its method and path. A write without a method is a bug. */
+export declare function writeRoute(text: string): WriteRoute;
+/** The path with the record's key in place of `{id}`. */
+export declare function pathFor(route: WriteRoute, id?: string): string;
+export declare function entity<T extends AnyRecord = AnyRecord>(key: string, routes: EntityRoutes): Entity<T>;

package/dist/core/entity.js

@@ -0,0 +1,32 @@
+const METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** `"POST /invoices/{id}/confirm"` → its method and path. A write without a method is a bug. */
+export function writeRoute(text) {
+    const [method, path] = text.trim().split(/\s+/, 2);
+    if (!METHODS.has(method) || path === undefined)
+        throw new Error(`"${text}" is not "METHOD /path": a write says how it is sent`);
+    return { method: method, path };
+}
+/** The path with the record's key in place of `{id}`. */
+export function pathFor(route, id) {
+    return id === undefined ? route.path : route.path.replace("{id}", encodeURIComponent(id));
+}
+export function entity(key, routes) {
+    if (!/^[^:\s]+:[^:\s]+$/.test(key))
+        throw new Error(`entity key "${key}" is not domain:kind`);
+    const list = routes.list.split("?")[0] ?? routes.list;
+    const template = routes.one ?? `${list}/{id}`;
+    const [domain = "", kind = ""] = key.split(":");
+    return {
+        key,
+        domain,
+        kind,
+        ref: (id) => ({ domain, kind, ...(id === undefined || id === "" ? {} : { id }) }),
+        list: routes.list,
+        one: (id) => template.replace("{id}", encodeURIComponent(id)),
+        commands: Object.fromEntries(Object.entries(routes.commands ?? {}).map(([name, text]) => [name, writeRoute(text)])),
+        ...(routes.save === undefined ? {} : { save: writeRoute(routes.save) }),
+        ...(routes.preview === undefined ? {} : { preview: writeRoute(routes.preview) }),
+        ...(routes.draft === undefined ? {} : { draft: writeRoute(routes.draft) }),
+        ...(routes.history === undefined ? {} : { history: routes.history }),
+    };
+}

package/dist/core/history.d.ts

@@ -0,0 +1,20 @@
+import { type AnyRecord, type Meta } from "@sincpro/criteria";
+/**
+ * A record's history as people read it — its business events, newest first.
+ *
+ * Context: sincpro_framework keeps every context's facts in one event table, read over
+ * `GET /<context>-events`, each fact naming the record it is about (`entity_type`,
+ * `entity_id`) and carrying a `label` in every language — the framework's `history_of`.
+ * forge's console read it with a dictionary of field names written by hand; here the words for
+ * the rest of a fact come from the events' own model definition, like any other field.
+ *
+ * These are business facts («Factura confirmada»), never technical logs: those belong to the
+ * observability stack, not to a record's screen.
+ */
+export type HistoryEntry = {
+    id: string;
+    label: string;
+    at: string;
+    detail?: string;
+};
+export declare function historyOf(rows: readonly AnyRecord[], meta: Meta | null | undefined, locale?: string): HistoryEntry[];

package/dist/core/history.js

@@ -0,0 +1,40 @@
+import { labelOf } from "@sincpro/criteria";
+/** What every fact carries: what remains is what this fact says. */
+const ENVELOPE = new Set([
+    "id",
+    "created_at",
+    "updated_at",
+    "version",
+    "label",
+    "entity_type",
+    "entity_id",
+    "entity_version",
+    "correlation_id",
+    "causation_id",
+]);
+function said(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    if (Array.isArray(value))
+        return value.length === 0 ? null : value.map(String).join(", ");
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+export function historyOf(rows, meta, locale) {
+    return rows.map((row) => {
+        const label = row["label"];
+        const word = typeof label === "string"
+            ? label
+            : ((locale ? label?.[locale] : undefined) ?? label?.["default"] ?? String(row["id"]));
+        const parts = Object.entries(row)
+            .filter(([key]) => !ENVELOPE.has(key))
+            .map(([key, value]) => [key, said(value)])
+            .filter(([, value]) => value !== null && value !== row["entity_id"])
+            .map(([key, value]) => `${labelOf(meta, key, locale)}: ${value}`);
+        return {
+            id: String(row["id"]),
+            label: word,
+            at: String(row["created_at"] ?? ""),
+            ...(parts.length === 0 ? {} : { detail: parts.join(" · ") }),
+        };
+    });
+}

package/dist/core/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The plain logic: no React, no DOM, no design system — so it is tested in Node, fast, with
+ * no browser. The transport, the entity, the model definition and what a value reads as.
+ * `make doctor` keeps it that way.
+ */
+export { type CachedTransport, cachedTransport, type CacheOptions, } from "./cache.js";
+export { ENGLISH_FRAMEWORK_COPY, type FrameworkCopy, frameworkCopy, installFrameworkCopy, SPANISH_FRAMEWORK_COPY, } from "./copy.js";
+export { changesOf, errorsByField, type FieldState, fieldStateOf, type FieldStates, missingOf, } from "./edit.js";
+export { type Entity, entity, type EntityRef, type EntityRoutes, pathFor, type WriteRoute, writeRoute, } from "./entity.js";
+export { type HistoryEntry, historyOf } from "./history.js";
+export { lookupOf, type LookupOption } from "./lookup.js";
+export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./memory.js";
+export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./meta.js";
+export { type MetaStore, metaStore } from "./metas.js";
+export { BOOKKEEPING, defaultFields, type FieldView, sortKeyOf, textOf, viewOf, } from "./present.js";
+export { type Related, relatedOf } from "./related.js";
+export { type RestOptions, restTransport, urlOf } from "./rest.js";
+export { completeMeta, type JsonSchema, metaFromSchema, type SchemaComponents, } from "./schema.js";
+export { type Draft, explain, type Method, type One, type Transport, TransportError, } from "./transport.js";

package/dist/core/index.js

@@ -0,0 +1,19 @@
+/**
+ * The plain logic: no React, no DOM, no design system — so it is tested in Node, fast, with
+ * no browser. The transport, the entity, the model definition and what a value reads as.
+ * `make doctor` keeps it that way.
+ */
+export { cachedTransport, } from "./cache.js";
+export { ENGLISH_FRAMEWORK_COPY, frameworkCopy, installFrameworkCopy, SPANISH_FRAMEWORK_COPY, } from "./copy.js";
+export { changesOf, errorsByField, fieldStateOf, missingOf, } from "./edit.js";
+export { entity, pathFor, writeRoute, } from "./entity.js";
+export { historyOf } from "./history.js";
+export { lookupOf } from "./lookup.js";
+export { memoryTransport, } from "./memory.js";
+export { defineMeta, field, } from "./meta.js";
+export { metaStore } from "./metas.js";
+export { BOOKKEEPING, defaultFields, sortKeyOf, textOf, viewOf, } from "./present.js";
+export { relatedOf } from "./related.js";
+export { restTransport, urlOf } from "./rest.js";
+export { completeMeta, metaFromSchema, } from "./schema.js";
+export { explain, TransportError, } from "./transport.js";

package/dist/core/lookup.d.ts

@@ -0,0 +1,16 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+/**
+ * A record as a choice: what a many2one select, a «share with» and ⌘K show for it.
+ *
+ * Context: sincpro_framework answers this question on its own — `LiteralSearch`, the entity's
+ * `DEFAULT_LITERAL_SEARCH` and `DEFAULT_DISPLAY` — and publishes both in the model definition
+ * (`meta.search`, `meta.display`). So a choice is read from the model: its key is the field a
+ * record is fetched by, its label the display, and the key again beside it when the two differ
+ * («Globex Bolivia · C-004»), which is what tells two «Globex» apart.
+ */
+export type LookupOption = {
+    id: string;
+    label: string;
+    detail?: string;
+};
+export declare function lookupOf(meta: Meta | null | undefined, rows: readonly AnyRecord[]): LookupOption[];

package/dist/core/lookup.js

@@ -0,0 +1,10 @@
+export function lookupOf(meta, rows) {
+    const key = meta?.get_id || meta?.identity || "id";
+    const display = meta?.display || key;
+    return rows.map((row) => {
+        const id = String(row[key] ?? "");
+        const shown = row[display];
+        const label = shown === undefined || shown === null || shown === "" ? id : String(shown);
+        return label === id ? { id, label } : { id, label, detail: id };
+    });
+}

package/dist/core/memory.d.ts

@@ -0,0 +1,43 @@
+import type { AnyRecord, Criteria, Meta, Problem } from "@sincpro/criteria";
+import { type Draft, type Method, type Transport } from "./transport.js";
+/**
+ * A server held in memory: tables of rows with their definition, answered with the same
+ * engine sincpro_framework's criteria runs on.
+ *
+ * Context: not a test double. It is what a screen runs against before its server exists,
+ * what Storybook and the tests run against, and what a domain with no server at all uses —
+ * rows a screen already holds. It filters, orders, pages and counts
+ * exactly as the server would (`answer` from `@sincpro/criteria/engine`), drops what the
+ * model cannot answer and reports it, and refuses what the server would refuse. So the day a
+ * real server answers, only the transport changes.
+ *
+ * A record is found at `<list route>/<id>`, by the field the model fetches by (`get_id`, else
+ * the identity) — the convention sincpro_framework's REST routes follow.
+ *
+ *     const transport = memoryTransport({
+ *       "/invoices": { meta: invoiceMeta, rows: invoices },
+ *     }, { latency: 300 });
+ */
+export type MemoryTable = {
+    meta: Meta;
+    rows: readonly AnyRecord[];
+};
+export type MemoryOptions = {
+    /** Milliseconds every answer waits, so a screen's «loading» can be seen and tested. */
+    latency?: number;
+    /**
+     * Answer a Command — a write, an action, a preview — the way the service would. It may
+     * change the tables' rows (they are read on every request) and throw a `TransportError` to
+     * refuse. Without it, every Command is a 404.
+     */
+    handle?: (method: Method, route: string, body: unknown) => unknown;
+    /** The draft this caller kept of a record, answered with it — sincpro_framework's `Drafts`. */
+    draft?: (route: string) => Draft | null;
+    /** Every list request, as it arrived: what a story or a test checks was really asked. */
+    observe?: (route: string, criteria: Criteria) => void;
+    /** Refuse a route the way a server would: return the problem it answers with. */
+    refuse?: (route: string) => (Problem & {
+        status?: number;
+    }) | undefined;
+};
+export declare function memoryTransport(tables: Readonly<Record<string, MemoryTable>>, options?: MemoryOptions): Transport;

package/dist/core/memory.js

@@ -0,0 +1,85 @@
+import { answer } from "@sincpro/criteria/engine";
+import { TransportError, } from "./transport.js";
+function wait(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((done, failed) => {
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            failed(signal.reason);
+        });
+    });
+}
+export function memoryTransport(tables, options = {}) {
+    async function check(route, signal) {
+        await wait(options.latency ?? 0, signal);
+        const refused = options.refuse?.(route);
+        if (refused !== undefined)
+            throw new TransportError(route, refused.status ?? 400, refused);
+    }
+    function tableAt(route) {
+        const path = route.split("?")[0] ?? route;
+        const table = tables[path];
+        if (table === undefined)
+            throw new TransportError(route, 404, {
+                kind: "not_found",
+                reason: "ROUTE_NOT_FOUND",
+                next_step: "fix_request",
+                retryable: false,
+                errors: [],
+                extensions: {},
+                detail: `No table answers ${path}.`,
+            });
+        return table;
+    }
+    return {
+        async list(route, criteria, signal) {
+            options.observe?.(route, criteria);
+            await check(route, signal);
+            const table = tableAt(route);
+            const page = answer(table.rows, criteria, table.meta);
+            // A copy, as over a wire: a screen holding a row must not see the server change it.
+            return { ...page, rows: structuredClone(page.rows) };
+        },
+        async one(route, signal) {
+            await check(route, signal);
+            const slash = route.lastIndexOf("/");
+            const table = tableAt(route.slice(0, slash));
+            const id = decodeURIComponent(route.slice(slash + 1));
+            const key = table.meta.get_id || table.meta.identity;
+            const record = table.rows.find((row) => String(row[key]) === id);
+            if (record === undefined)
+                throw new TransportError(route, 404, {
+                    kind: "not_found",
+                    reason: "AGGREGATE_NOT_FOUND",
+                    next_step: "do_not_retry",
+                    retryable: false,
+                    errors: [],
+                    extensions: {},
+                    detail: `${table.meta.aggregate} ${id} does not exist.`,
+                });
+            return {
+                record: structuredClone(record),
+                meta: table.meta,
+                dropped: [],
+                draft: options.draft?.(route) ?? null,
+            };
+        },
+        async send(method, route, body, signal) {
+            await check(route, signal);
+            if (options.handle === undefined)
+                throw new TransportError(route, 404, {
+                    kind: "not_found",
+                    reason: "ROUTE_NOT_FOUND",
+                    next_step: "fix_request",
+                    retryable: false,
+                    errors: [],
+                    extensions: {},
+                    detail: `Nothing answers ${method} ${route}.`,
+                });
+            // A deep copy: what the caller sent is not what the server keeps.
+            return (await options.handle(method, route, structuredClone(body)));
+        },
+    };
+}

package/dist/core/meta.d.ts

@@ -0,0 +1,114 @@
+import type { Expression, FieldMeta, FieldType, Meta, Operator } from "@sincpro/criteria";
+/**
+ * A model definition written by hand, in the shape sincpro_framework publishes.
+ *
+ * Context: everything in this package reads a `Meta` — the labels, the columns, the controls,
+ * the search box. A service built with sincpro_framework sends one with every answer. A domain
+ * that has none (another backend, rows a screen already holds, a prototype
+ * with no server yet) declares it here, and from then on it is indistinguishable: the same
+ * list, the same record, the same criteria. `describeRows` from `@sincpro/criteria` guesses
+ * one from rows; this one is written on purpose, with the words a person reads.
+ *
+ *     const tickets = defineMeta({
+ *       aggregate: "Ticket", identity: "id", display: "title", search: ["title"],
+ *       name: { es: "Tickets" },
+ *       fields: {
+ *         id: field.text({ readonly: true }),
+ *         title: field.text({ label: { es: "Título" }, required: true }),
+ *         stage: field.choice(["new", "done"], { labels: { new: { es: "Nuevo" } } }),
+ *         opened_at: field.datetime({ label: { es: "Abierto" } }),
+ *       },
+ *     });
+ */
+/** A word in several languages, `{default?, es?, en?, …}`; a bare string is the default. */
+export type Words = string | Readonly<Record<string, string>>;
+export type FieldOptions = {
+    label?: Words;
+    help?: Words;
+    required?: boolean;
+    readonly?: boolean;
+    /** Holds no value sometimes. A nullable field is never sortable: keyset paging over it
+     *  loses the rows that hold NULL, which is why the framework refuses to order by one. */
+    nullable?: boolean;
+    default?: unknown;
+    /** Form hints over the record, as sincpro_framework's `Presentation` publishes them. */
+    readonlyWhen?: Expression;
+    requiredWhen?: Expression;
+    visibleWhen?: Expression;
+};
+/** The field builders: one per type the framework publishes. */
+export declare const field: {
+    text: (options?: FieldOptions) => FieldMeta;
+    integer: (options?: FieldOptions) => FieldMeta;
+    /** A decimal travels as text so no digit is lost (`"10.50"`): pass `exact: true`. */
+    number: (options?: FieldOptions & {
+        exact?: boolean;
+    }) => {
+        exact?: boolean;
+        type: FieldType;
+        nullable: boolean;
+        choices?: unknown[];
+        choice_labels?: Record<string, Record<string, string>>;
+        label?: Record<string, string>;
+        help?: Record<string, string>;
+        groupable?: boolean;
+        aggregates?: string[];
+        computed?: boolean;
+        owner?: string | null;
+        readonly?: boolean;
+        required?: boolean;
+        default?: unknown;
+        readonly_when?: Expression | null;
+        required_when?: Expression | null;
+        visible_when?: Expression | null;
+        sortable: boolean;
+        ops: Operator[];
+        many?: boolean;
+        relation?: string | null;
+        identified_by?: string | null;
+        parent_field?: string | null;
+        related_field?: string | null;
+        definition?: Meta | null;
+        kind: import("@sincpro/criteria").FieldKind;
+    };
+    boolean: (options?: FieldOptions) => FieldMeta;
+    date: (options?: FieldOptions) => FieldMeta;
+    datetime: (options?: FieldOptions) => FieldMeta;
+    tags: (options?: FieldOptions) => FieldMeta;
+    /** An enum: the values in order, and the word each one is read as. */
+    choice: (values: readonly string[], options?: FieldOptions & {
+        labels?: Readonly<Record<string, Words>>;
+    }) => FieldMeta;
+    /** Points at ONE record of another aggregate, by the scalar key this record holds. */
+    many2one: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    /** The records of another aggregate that point back here, by THEIR key. */
+    one2many: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    many2many: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    /** A value object kept inside the record — an address, a specification. No identity. */
+    embedded: (definition: Meta, options?: FieldOptions & {
+        many?: boolean;
+    }) => FieldMeta;
+};
+export type MetaSpec = {
+    aggregate: string;
+    identity: string;
+    fields: Record<string, FieldMeta>;
+    name?: Words;
+    /** The field shown beside the identity: what a select and a many2one show. */
+    display?: string;
+    /** `"-created_at"`, the way a URL writes it. Without it, the identity ascending. */
+    defaultOrder?: string;
+    /** The text fields a typed text is looked for in — the entity's search template. */
+    search?: readonly string[];
+};
+/** A whole definition, from its fields. See the file header. */
+export declare function defineMeta(spec: MetaSpec): Meta;

package/dist/core/meta.js

@@ -0,0 +1,130 @@
+function hints(options) {
+    return {
+        ...(options.readonlyWhen ? { readonly_when: options.readonlyWhen } : {}),
+        ...(options.requiredWhen ? { required_when: options.requiredWhen } : {}),
+        ...(options.visibleWhen ? { visible_when: options.visibleWhen } : {}),
+    };
+}
+/** The comparisons each type takes — the same table sincpro_framework publishes. */
+const OPS = {
+    text: ["=", "!=", "like", "starts with", "in", "not in"],
+    integer: ["=", "!=", ">", ">=", "<", "<=", "between", "in", "not in"],
+    number: ["=", "!=", ">", ">=", "<", "<=", "between", "in", "not in"],
+    date: ["=", "!=", ">", ">=", "<", "<=", "between"],
+    datetime: ["=", "!=", ">", ">=", "<", "<=", "between"],
+    boolean: ["="],
+    "text[]": ["contains", "not contains", "=", "!="],
+};
+function words(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" ? { default: value } : { ...value };
+}
+function scalar(type, options = {}) {
+    const nullable = options.nullable ?? false;
+    const ops = [...(OPS[type] ?? [])];
+    if (nullable && type !== "text[]" && type !== "boolean")
+        ops.push("is null");
+    const listed = type === "text[]";
+    return {
+        type,
+        kind: "scalar",
+        nullable,
+        sortable: !nullable && !listed,
+        groupable: !listed,
+        ops,
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+        ...(options.help === undefined ? {} : { help: words(options.help) }),
+        ...(options.required === undefined ? {} : { required: options.required }),
+        ...(options.readonly === undefined ? {} : { readonly: options.readonly }),
+        ...(options.default === undefined ? {} : { default: options.default }),
+        ...hints(options),
+    };
+}
+function relational(type, relation, keys, options = {}) {
+    return {
+        type,
+        kind: "relation",
+        nullable: options.nullable ?? type === "many2one",
+        sortable: false,
+        ops: [],
+        many: type !== "many2one",
+        relation,
+        identified_by: keys.identifiedBy,
+        ...(keys.definition === undefined ? {} : { definition: keys.definition }),
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+        ...(options.help === undefined ? {} : { help: words(options.help) }),
+        ...(options.readonly === undefined ? {} : { readonly: options.readonly }),
+    };
+}
+/** The field builders: one per type the framework publishes. */
+export const field = {
+    text: (options) => scalar("text", options),
+    integer: (options) => scalar("integer", options),
+    /** A decimal travels as text so no digit is lost (`"10.50"`): pass `exact: true`. */
+    number: (options) => ({
+        ...scalar("number", options),
+        ...(options?.exact ? { exact: true } : {}),
+    }),
+    boolean: (options) => scalar("boolean", options),
+    date: (options) => scalar("date", options),
+    datetime: (options) => scalar("datetime", options),
+    tags: (options) => scalar("text[]", options),
+    /** An enum: the values in order, and the word each one is read as. */
+    choice: (values, options = {}) => ({
+        ...scalar("text", options),
+        ops: ["=", "!=", "in", "not in", ...(options.nullable ? ["is null"] : [])],
+        choices: [...values],
+        ...(options.labels === undefined
+            ? {}
+            : {
+                choice_labels: Object.fromEntries(Object.entries(options.labels).map(([value, said]) => [value, words(said) ?? {}])),
+            }),
+    }),
+    /** Points at ONE record of another aggregate, by the scalar key this record holds. */
+    many2one: (relation, keys, options) => relational("many2one", relation, keys, options),
+    /** The records of another aggregate that point back here, by THEIR key. */
+    one2many: (relation, keys, options) => relational("one2many", relation, keys, options),
+    many2many: (relation, keys, options) => relational("many2many", relation, keys, options),
+    /** A value object kept inside the record — an address, a specification. No identity. */
+    embedded: (definition, options = {}) => ({
+        type: "embedded",
+        kind: "embedded",
+        nullable: options.nullable ?? false,
+        sortable: false,
+        ops: [],
+        definition,
+        ...(options.many ? { many: true } : {}),
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+    }),
+};
+/** The template a typed text fills: `like` over each field, any of them matching. */
+function searchTemplate(fields) {
+    if (fields.length === 0)
+        return null;
+    const like = (name) => ({
+        field: name,
+        operator: "like",
+        value: { $: "param", name: "text" },
+    });
+    const [only] = fields;
+    return {
+        where: fields.length === 1 && only !== undefined ? like(only) : { any: fields.map(like) },
+    };
+}
+/** A whole definition, from its fields. See the file header. */
+export function defineMeta(spec) {
+    const missing = [spec.identity, spec.display, ...(spec.search ?? [])].filter((name) => name !== undefined && name !== "" && !(name in spec.fields));
+    if (missing.length > 0)
+        throw new Error(`${spec.aggregate}: ${missing.join(", ")} named but not declared`);
+    return {
+        aggregate: spec.aggregate,
+        identity: spec.identity,
+        default_order: spec.defaultOrder ?? spec.identity,
+        fields: spec.fields,
+        get_id: spec.identity,
+        ...(spec.name === undefined ? {} : { name: words(spec.name) }),
+        ...(spec.display === undefined ? {} : { display: spec.display }),
+        search: searchTemplate(spec.search ?? []),
+    };
+}

package/dist/core/metas.d.ts

@@ -0,0 +1,18 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * The model definitions already known, by entity key (`"billing:invoice"`).
+ *
+ * Context: sincpro_framework sends `entity_meta_data` with every answer that does not say
+ * `meta: false`, and it is not small — forge's `Project` weighs ~97 KB even with zero rows.
+ * A reading already asks for it only on its first page; this keeps it ACROSS readings, so the
+ * second list of the same entity, the record opened from it and the select that points at it
+ * ask with `meta: false` and draw their labels before the rows arrive.
+ *
+ * Seeded, it is the preload: definitions written at build time (a snapshot of the server's,
+ * or `defineMeta`) reach the first screen with no request at all.
+ */
+export type MetaStore = {
+    get(key: string): Meta | undefined;
+    set(key: string, meta: Meta): void;
+};
+export declare function metaStore(seed?: Readonly<Record<string, Meta>>): MetaStore;

package/dist/core/metas.js

@@ -0,0 +1,7 @@
+export function metaStore(seed = {}) {
+    const known = new Map(Object.entries(seed));
+    return {
+        get: (key) => known.get(key),
+        set: (key, meta) => void known.set(key, meta),
+    };
+}