@sincpro/client-framework 0.0.0-stage → 0.2.0

package/dist/codegen/metamodel.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The client contract of a bounded context, as sincpro_framework exports it
+ * (`export_client_contract`, PRD_33): its metamodel — models, the definitions they share, every
+ * operation a client may call — and how each wire reaches each operation (`bindings`). A bare
+ * metamodel (`export_metamodel`) is the same without `format` and `bindings`.
+ *
+ * Context: only what the generator reads is typed here. The file is the server's, written with
+ * its keys sorted, so the same code writes the same bytes; a key this does not name is kept in
+ * the snapshot and ignored by the generator.
+ */
+export type Schema = {
+    type?: string | readonly string[];
+    format?: string;
+    enum?: readonly unknown[];
+    const?: unknown;
+    items?: Schema;
+    $ref?: string;
+    anyOf?: readonly Schema[];
+    oneOf?: readonly Schema[];
+    properties?: Readonly<Record<string, Schema>>;
+    required?: readonly string[];
+    additionalProperties?: boolean | Schema;
+    title?: string;
+    description?: string;
+    "x-sincpro"?: {
+        type?: string;
+        relation?: string | null;
+        identity?: string;
+    };
+};
+export type Operation = {
+    /** What it is for its entity: `search`, `get`, `edit`, `command`… */
+    role: string;
+    /** It writes nothing: retrying or caching it is safe. */
+    query: boolean;
+    entities: readonly string[];
+    /** The field of `input` that names the record of each entity it runs on. */
+    targets: Readonly<Record<string, string>>;
+    dry_run: boolean;
+    description?: string | null;
+    input: Schema;
+    /** What it answers; `null` when the server declares nothing. */
+    output: Schema | null;
+    /** The entity's own operation of its role, when it has several (`@entity_tags(own=True)`). */
+    own?: boolean;
+    deprecated?: boolean;
+    /** The day it stops being served, `YYYY-MM-DD`. */
+    sunset?: string | null;
+    /** The operation that replaces it, by identity. */
+    replacement?: string | null;
+};
+/** How REST reaches an operation: its method and its whole path, `{field}` where a field goes. */
+export type RestBinding = {
+    method: string;
+    path: string;
+    /** The fields of the input the path carries. */
+    path_fields: readonly string[];
+};
+export type Bindings = {
+    rest?: Readonly<Record<string, RestBinding>>;
+    rpc?: Readonly<Record<string, {
+        method: string;
+    }>>;
+    grpc?: Readonly<Record<string, {
+        method: string;
+    }>>;
+    mcp?: Readonly<Record<string, {
+        tool: string;
+    }>>;
+};
+export type Metamodel = {
+    /** `sincpro.client-contract/1` for an exported client contract. */
+    format?: string;
+    /** The bounded context's own name: what every operation's identity starts with. */
+    bounded_context?: string;
+    /** The name the gateways publish it under (`FastApiGateway({"project": …})`): what a client
+     *  names the context by. */
+    alias?: string;
+    /** The bounded context's name, as sincpro_framework 3.32 wrote it before `bounded_context`. */
+    context?: string;
+    version: string;
+    /** Every shape the contract names: an entity (it has an `identity`) or a value it holds. */
+    models: Readonly<Record<string, Schema>>;
+    /** By the Command's identity, `"<bounded_context>.<Class>"`. */
+    operations: Readonly<Record<string, Operation>>;
+    $defs?: Readonly<Record<string, Schema>>;
+    /** By wire, then by the Command's identity. */
+    bindings?: Bindings;
+};

package/dist/codegen/metamodel.js

@@ -0,0 +1 @@
+export {};

package/dist/codegen/names.d.ts

@@ -0,0 +1,39 @@
+import type { Metamodel } from "./metamodel.js";
+/**
+ * What a generated file imports, built in parts. The build rewrites this package's own
+ * specifiers to relative paths (`tsc-alias`), and it reads `from "…"` inside a string too: written
+ * whole, the generated files came out importing `"../index.js"` and `"./domain.js"`.
+ */
+export declare const FRAMEWORK: string;
+export declare const DOMAIN_MODULE: string;
+/** A name of the server's as a TypeScript identifier: `shop__orders__Line` stays, `-` is `_`. */
+export declare function identifierOf(name: string): string;
+/** A property key as TypeScript writes it: bare when it can be, quoted otherwise. */
+export declare function keyOf(name: string): string;
+export declare function sorted<V>(record: Readonly<Record<string, V>>): [string, V][];
+/** `{ Issue: "issue_id" }`: a record of texts as TypeScript writes it, keys sorted. */
+export declare function recordLiteral(record: Readonly<Record<string, string>>): string;
+/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+export declare function contextOf(metamodel: Metamodel): string;
+/** What a client names the context by: its `alias`, else its own name. */
+export declare function aliasOf(metamodel: Metamodel): string;
+/** A model the contract names is an entity when it has an identity; else a value it holds. */
+export declare function isEntity(metamodel: Metamodel, model: string): boolean;
+/** An operation's name in its context: its identity without `<bounded_context>.`. */
+export declare function localOf(metamodel: Metamodel, identity: string): string;
+/** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
+export declare function methodOf(local: string): string;
+/** `Issue` → `issues`, `ProjectEvent` → `projectEvents`, `Policy` → `policies`. */
+export declare function pluralOf(name: string): string;
+/** A JSDoc block, or nothing: the paragraphs given, each one kept. */
+export declare function docOf(lines: readonly (string | null | undefined)[], pad: string): string;
+/** The first lines of every generated file: what it is, where it came from, not to edit it. */
+export declare function headerOf(what: string, metamodel: Metamodel): string;
+/** What a deprecated operation says: since when it goes and what replaces it. */
+export declare function deprecationOf(metamodel: Metamodel, operation: {
+    deprecated?: boolean;
+    sunset?: string | null;
+    replacement?: string | null;
+}): string | undefined;
+/** Refuses a second thing under a name already given, naming both. */
+export declare function claimed(): (name: string, by: string) => void;

package/dist/codegen/names.js

@@ -0,0 +1,113 @@
+/**
+ * How the generator names what the server names: a TypeScript identifier for a class, a method
+ * for an operation, a value for an entity, the key the workspace refers to an entity by.
+ *
+ * Context: every name here is derived, the same way every time, from what the contract already
+ * says — never chosen — so regenerating never renames by itself. Two things that come out with
+ * one name are refused by whoever writes them, naming both (`claimed`): a silent rename would
+ * break whoever imported the first.
+ */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * What a generated file imports, built in parts. The build rewrites this package's own
+ * specifiers to relative paths (`tsc-alias`), and it reads `from "…"` inside a string too: written
+ * whole, the generated files came out importing `"../index.js"` and `"./domain.js"`.
+ */
+export const FRAMEWORK = ["@sincpro", "client-framework"].join("/");
+export const DOMAIN_MODULE = [".", "domain"].join("/");
+/** A name of the server's as a TypeScript identifier: `shop__orders__Line` stays, `-` is `_`. */
+export function identifierOf(name) {
+    const cleaned = name.replace(/[^A-Za-z0-9_$]/g, "_");
+    return /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+/** A property key as TypeScript writes it: bare when it can be, quoted otherwise. */
+export function keyOf(name) {
+    return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+export function sorted(record) {
+    return Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** `{ Issue: "issue_id" }`: a record of texts as TypeScript writes it, keys sorted. */
+export function recordLiteral(record) {
+    const entries = sorted(record).map(([key, value]) => `${keyOf(key)}: ${JSON.stringify(value)}`);
+    return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+}
+/** The bounded context's own name: `bounded_context`, or `context` in a 3.32 contract. */
+export function contextOf(metamodel) {
+    const name = metamodel.bounded_context ?? metamodel.context;
+    if (name === undefined)
+        throw new Error("the contract names no bounded context");
+    return name;
+}
+/** What a client names the context by: its `alias`, else its own name. */
+export function aliasOf(metamodel) {
+    return metamodel.alias ?? contextOf(metamodel);
+}
+/** A model the contract names is an entity when it has an identity; else a value it holds. */
+export function isEntity(metamodel, model) {
+    return metamodel.models[model]?.["x-sincpro"]?.identity !== undefined;
+}
+/** An operation's name in its context: its identity without `<bounded_context>.`. */
+export function localOf(metamodel, identity) {
+    const prefix = `${contextOf(metamodel)}.`;
+    return identifierOf(identity.startsWith(prefix) ? identity.slice(prefix.length) : identity);
+}
+/** The method an operation is called by: `CommandSendIssue` → `sendIssue`. */
+export function methodOf(local) {
+    const bare = local.replace(/^(Command|Query)(?=[A-Z])/, "");
+    return `${bare.charAt(0).toLowerCase()}${bare.slice(1)}`;
+}
+/** `Issue` → `issues`, `ProjectEvent` → `projectEvents`, `Policy` → `policies`. */
+export function pluralOf(name) {
+    const value = `${name.charAt(0).toLowerCase()}${name.slice(1)}`;
+    if (/[^aeiou]y$/.test(value))
+        return `${value.slice(0, -1)}ies`;
+    if (/(s|x|z|ch|sh)$/.test(value))
+        return `${value}es`;
+    return `${value}s`;
+}
+/** A JSDoc block, or nothing: the paragraphs given, each one kept. */
+export function docOf(lines, pad) {
+    const text = lines
+        .filter((one) => typeof one === "string" && one.trim() !== "")
+        .join("\n\n")
+        .replace(/\*\//g, "*\\/")
+        .trim();
+    if (text === "")
+        return "";
+    const parts = text.split("\n");
+    if (parts.length === 1)
+        return `${pad}/** ${parts[0]} */\n`;
+    const body = parts.map((one) => `${pad} *${one === "" ? "" : ` ${one}`}`).join("\n");
+    return `${pad}/**\n${body}\n${pad} */\n`;
+}
+/** The first lines of every generated file: what it is, where it came from, not to edit it. */
+export function headerOf(what, metamodel) {
+    const alias = aliasOf(metamodel);
+    const own = contextOf(metamodel);
+    return [
+        `// ${what} of «${alias}»${alias === own ? "" : ` (${own})`}, generated by @sincpro/client-framework.`,
+        `// Version ${metamodel.version}.`,
+        `// Do not edit: regenerate it (\`sincpro-client generate\`).`,
+    ].join("\n");
+}
+/** What a deprecated operation says: since when it goes and what replaces it. */
+export function deprecationOf(metamodel, operation) {
+    if (operation.deprecated !== true)
+        return undefined;
+    const sunset = operation.sunset ? ` It stops being served on ${operation.sunset}.` : "";
+    const replacement = operation.replacement
+        ? ` Use \`${localOf(metamodel, operation.replacement)}\`.`
+        : "";
+    return `@deprecated${sunset}${replacement}`;
+}
+/** Refuses a second thing under a name already given, naming both. */
+export function claimed() {
+    const named = new Map();
+    return (name, by) => {
+        const before = named.get(name);
+        if (before !== undefined)
+            throw new Error(`${by} and ${before} are both "${name}" in TypeScript: rename one`);
+        named.set(name, by);
+    };
+}

package/dist/codegen/rest.d.ts

@@ -0,0 +1,31 @@
+import type { Metamodel, Operation } from "./metamodel.js";
+/**
+ * How REST reaches each operation of a contract, as the generated client and entities write it.
+ *
+ * Context: the export names each path whole (`/v1/issues/{issue_id}`), version included, while
+ * an application's transport already prepends it (`restTransport({ base: "/v1" })`). `base`
+ * takes it off every path, and a path outside it is refused — a client written with half its
+ * routes under the wrong base would fail one call at a time.
+ */
+export type GenerateOptions = {
+    /** The first part of every entity's key: `project` makes `project:issue`. The contract's
+     *  `alias` by default. */
+    domain?: string;
+    /** What every REST path starts with and the transport prepends: `/v1`. */
+    base?: string;
+};
+export type Reached = {
+    method: string;
+    /** The path under `base`, `{field}` where a field of the input goes. */
+    path: string;
+    /** The fields of the input the path carries. */
+    fields: readonly string[];
+};
+/** What a transport can send: GET is read by `list` (a page) or `one` (a record) only. */
+export declare const WRITES: Set<string>;
+export declare function restOf(metamodel: Metamodel, identity: string, options: GenerateOptions): Reached | undefined;
+/**
+ * The one entity a read belongs to: its only entity, or — when it concerns several — the one
+ * whose model its answer carries. `undefined` when that still leaves more than one.
+ */
+export declare function ownerOf(metamodel: Metamodel, operation: Operation): string | undefined;

package/dist/codegen/rest.js

@@ -0,0 +1,27 @@
+/** What a transport can send: GET is read by `list` (a page) or `one` (a record) only. */
+export const WRITES = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+export function restOf(metamodel, identity, options) {
+    const binding = metamodel.bindings?.rest?.[identity];
+    if (binding === undefined)
+        return undefined;
+    const base = options.base ?? "";
+    const under = base === "" || binding.path === base || binding.path.startsWith(`${base}/`);
+    if (!under)
+        throw new Error(`${identity} is at ${binding.path}, outside the base ${base}`);
+    return {
+        method: binding.method.toUpperCase(),
+        path: binding.path.slice(base.length) || "/",
+        fields: binding.path_fields,
+    };
+}
+/**
+ * The one entity a read belongs to: its only entity, or — when it concerns several — the one
+ * whose model its answer carries. `undefined` when that still leaves more than one.
+ */
+export function ownerOf(metamodel, operation) {
+    if (operation.entities.length === 1)
+        return operation.entities[0];
+    const answer = JSON.stringify(operation.output ?? {});
+    const carried = operation.entities.filter((one) => one in metamodel.models && answer.includes(`"#/models/${one}"`));
+    return carried.length === 1 ? carried[0] : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The public entry of @sincpro/client-framework: everything a client of a sincpro_framework
+ * service needs, on any platform.
+ *
+ * Context: one entry, not one per area — the package has no side effects at import
+ * (`sideEffects: false`), so an application pays only for what it uses, and a use case, the
+ * client it calls and the entity it reads come from the same place.
+ *
+ *   client/   the seam with a server: the transport and its REST and in-memory implementations,
+ *             entities with typed commands, the service's client contract, client-side ids
+ *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
+ *   services/ Feature and ApplicationService, the runtime they run in, what each run carries
+ *   observability/  the ports a platform plugs: a tracer and an error reporter
+ *
+ * The generator is `@sincpro/client-framework/codegen`, and the in-memory tracer and reporter
+ * `@sincpro/client-framework/testing`: neither is part of what an application runs.
+ */
+export { type ClientContract, entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
+export { bodyFor, type CommandAnswers, type CommandBodies, type CommandRoute, type Entity, entity, type EntityRef, type EntityRoutes, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, type SummaryFields, type SummaryPart, TRAIL_PARAM, WITH_PARAM, type WriteRoute, writeRoute, } from "./client/entity.js";
+export { isEntityId, newEntityId } from "./client/ids.js";
+export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./client/memory.js";
+export { type RestOptions, restTransport, urlOf, type VersionDrift, } from "./client/rest.js";
+export { type RetryKeys, retryKeys, unanswered, } from "./client/retry.js";
+export { type CallOptions, type Draft, type Method, type One, readRoute, type SendOptions, type Transport, TransportError, } from "./client/transport.js";
+export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./model/meta.js";
+export { type MetaStore, metaStore } from "./model/metas.js";
+export { completeMeta, type JsonSchema, metaFromSchema, type SchemaComponents, } from "./model/schema.js";
+export { type Attributes, type ErrorAbout, type ErrorReporter, NO_TRACER, type Outcome, type Span, type Tracer, } from "./observability/ports.js";
+export { BIND, type Bindable, bindable, bindDependency, bindTransport, type Execution, headersOf, } from "./services/execution.js";
+export { ApplicationService, bindServices, Feature, } from "./services/feature.js";
+export { createRuntime, DETACHED, outcomeOf, type Runtime, type RuntimeOptions, } from "./services/runtime.js";

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * The public entry of @sincpro/client-framework: everything a client of a sincpro_framework
+ * service needs, on any platform.
+ *
+ * Context: one entry, not one per area — the package has no side effects at import
+ * (`sideEffects: false`), so an application pays only for what it uses, and a use case, the
+ * client it calls and the entity it reads come from the same place.
+ *
+ *   client/   the seam with a server: the transport and its REST and in-memory implementations,
+ *             entities with typed commands, the service's client contract, client-side ids
+ *   model/    model definitions: written by hand, read from a JSON Schema, kept once known
+ *   services/ Feature and ApplicationService, the runtime they run in, what each run carries
+ *   observability/  the ports a platform plugs: a tracer and an error reporter
+ *
+ * The generator is `@sincpro/client-framework/codegen`, and the in-memory tracer and reporter
+ * `@sincpro/client-framework/testing`: neither is part of what an application runs.
+ */
+export { entityKeyOf, kindOf, metasOf, versionsOf, } from "./client/contract.js";
+export { bodyFor, entity, listRoute, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, SCOPE_PARAM, scopeOfRef, startingValuesOf, TRAIL_PARAM, WITH_PARAM, writeRoute, } from "./client/entity.js";
+export { isEntityId, newEntityId } from "./client/ids.js";
+export { memoryTransport, } from "./client/memory.js";
+export { restTransport, urlOf, } from "./client/rest.js";
+export { retryKeys, unanswered, } from "./client/retry.js";
+export { readRoute, TransportError, } from "./client/transport.js";
+export { defineMeta, field, } from "./model/meta.js";
+export { metaStore } from "./model/metas.js";
+export { completeMeta, metaFromSchema, } from "./model/schema.js";
+export { NO_TRACER, } from "./observability/ports.js";
+export { BIND, bindable, bindDependency, bindTransport, headersOf, } from "./services/execution.js";
+export { ApplicationService, bindServices, Feature, } from "./services/feature.js";
+export { createRuntime, DETACHED, outcomeOf, } from "./services/runtime.js";

package/dist/model/meta.d.ts

@@ -0,0 +1,121 @@
+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[];
+        widget?: string;
+        affects?: string[];
+        judged_by?: string[];
+        holds?: Expression | null;
+        computes?: import("@sincpro/criteria").Formula | null;
+        navigable?: boolean;
+        total?: string | null;
+        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/model/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 {
+        selection: 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/model/metas.d.ts

@@ -0,0 +1,17 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * The model definitions already known, by entity key (`"billing:invoice"`).
+ *
+ * Context: sincpro_framework publishes each model once, in the discovery document the
+ * transport reads (`core/discovery`); an answer carries only its version. This keeps the
+ * definitions ACROSS readings, so the second list of the same entity, the record opened from it
+ * and the select that points at it 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/model/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),
+    };
+}