@sincpro/client-framework 0.0.0-stage → 0.1.0

package/dist/client/rest.d.ts

@@ -0,0 +1,49 @@
+import { type Transport } from "./transport.js";
+import { type Criteria } from "@sincpro/criteria";
+/**
+ * The REST wire of sincpro_framework (`FastApiGateway`).
+ *
+ * Context: a list is criteria's `restSource` (0.3.1 sends the criteria as plain JSON and joins
+ * a route that carries its own query, `/projects?tenant_id=acme` — the two things forge's
+ * console found wrong in 0.3.0, fixed there). What this adds is what criteria does not know:
+ * one record (`one()`), a write (`send()`, with its `Idempotency-Key`), and its refusals as a
+ * `TransportError`, the one error every screen explains.
+ *
+ * The definition of each model — what a list, a form and a select are built from — is read
+ * from the bounded context's discovery document (`document`, `/openapi.json` by default), once,
+ * and read again only when an answer says another version of its model (`model_version`); the
+ * document is revalidated with its `ETag`, so an unchanged one costs a `304`.
+ *
+ *     const transport = restTransport({
+ *       base: "/v1",
+ *       headers: () => ({ Authorization: `Bearer ${session.secret}` }),
+ *     });
+ */
+export type RestOptions = {
+    /** Prepended to every route: `"/v1"`, `"https://forge.sincpro.com.bo/v1"`. */
+    base?: string;
+    /** Sent with every request. A function is called fresh each time — a token that rotates. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Defaults to the global `fetch`. Inject one for tests. */
+    fetch?: typeof fetch;
+    /** Where the bounded context's discovery document is: `"/openapi.json"` by default, at the
+     *  origin of `base`. `null`: none is read, and the definitions come only from `metas`. */
+    document?: string | null;
+    /**
+     * The version of each model the application was written against — the snapshot it was
+     * generated from (`versionsOf(contract)`). With it, an answer of another version is told to
+     * `onVersionDrift`: the server moved, the generated code did not.
+     */
+    snapshot?: Readonly<Record<string, string>>;
+    /** Called once per model and version the server answers that the snapshot does not hold —
+     *  never an error: the screen keeps working on the live definition. */
+    onVersionDrift?: (drift: VersionDrift) => void;
+};
+/** A model the server answers at another version than the snapshot the code came from. */
+export type VersionDrift = {
+    model: string;
+    snapshot: string;
+    live: string;
+};
+export declare function urlOf<T>(base: string, route: string, criteria?: Criteria<T>): string;
+export declare function restTransport(options?: RestOptions): Transport;

package/dist/client/rest.js

@@ -0,0 +1,143 @@
+import { definitionOf, modelAt, } from "./discovery.js";
+import { TransportError, } from "./transport.js";
+import { readProblem } from "@sincpro/criteria";
+import { RestError, restSource } from "@sincpro/criteria/rest";
+/** The keys of an answer that are not the record: what is left is the record's own field. */
+const ENVELOPE = new Set(["cursor", "count", "model_version", "dropped", "draft", "missing"]);
+export function urlOf(base, route, criteria) {
+    const url = `${base}${route}`;
+    if (criteria === undefined)
+        return url;
+    const joiner = url.includes("?") ? "&" : "?";
+    return `${url}${joiner}criteria=${encodeURIComponent(JSON.stringify(criteria))}`;
+}
+/** The path a route is asked at, without its query: what a document path is matched with. */
+function pathOf(url) {
+    const path = url.split("?")[0] ?? url;
+    return /^https?:\/\//.test(path) ? new URL(path).pathname : path;
+}
+/** Where the document is: `document` as given when absolute, else at the origin of `base`. */
+function documentUrl(base, document) {
+    if (/^https?:\/\//.test(document) || !/^https?:\/\//.test(base))
+        return document;
+    return new URL(document, base).toString();
+}
+export function restTransport(options = {}) {
+    const base = options.base ?? "";
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const own = () => typeof options.headers === "function" ? options.headers() : (options.headers ?? {});
+    // The discovery document, read once; asked again — with its ETag — when an answer says a
+    // version of its model the document did not.
+    const located = options.document === null ? null : (options.document ?? "/openapi.json");
+    let held;
+    let tag = null;
+    function documentRead(fresh) {
+        if (located === null)
+            return Promise.resolve(null);
+        if (held !== undefined && !fresh)
+            return held;
+        const before = held;
+        held = (async () => {
+            try {
+                const response = await doFetch(documentUrl(base, located), {
+                    headers: { ...own(), ...(tag === null ? {} : { "If-None-Match": tag }) },
+                });
+                if (response.status === 304 && before !== undefined)
+                    return await before;
+                if (!response.ok)
+                    return null;
+                tag = response.headers.get("etag");
+                return (await response.json());
+            }
+            catch {
+                return null;
+            }
+        })();
+        return held;
+    }
+    /** The definition of the model `url` answers; read again when `version` is not the one held. */
+    // Each drift is told once: a list read every few seconds would say it on every page.
+    const told = new Set();
+    function noticeDrift(model, live) {
+        const snapshot = options.snapshot?.[model];
+        if (snapshot === undefined || !live || live === snapshot)
+            return;
+        const key = `${model}\u0000${live}`;
+        if (told.has(key))
+            return;
+        told.add(key);
+        options.onVersionDrift?.({ model, snapshot, live });
+    }
+    async function definitionAt(url, method, version) {
+        const published = await documentRead(false);
+        if (published === null)
+            return null;
+        const name = modelAt(published, pathOf(url), method);
+        if (name === undefined)
+            return null;
+        noticeDrift(name, version);
+        const known = definitionOf(published, name);
+        if (known === undefined || !version || known.version === version)
+            return known?.meta ?? null;
+        const again = await documentRead(true);
+        return (again === null ? undefined : definitionOf(again, name))?.meta ?? known.meta;
+    }
+    async function get(route, url, signal, write, call) {
+        const headers = write
+            ? {
+                ...own(),
+                ...call?.headers,
+                "Content-Type": "application/json",
+                ...(write.key === undefined ? {} : { "Idempotency-Key": write.key }),
+            }
+            : { ...own(), ...call?.headers };
+        const response = await doFetch(url, {
+            headers,
+            ...(write ? { method: write.method, body: JSON.stringify(write.body) } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new TransportError(route, response.status, readProblem(text), undefined);
+        return text ? JSON.parse(text) : null;
+    }
+    return {
+        async list(route, criteria, signal, call) {
+            const source = restSource(`${base}${route}`, {
+                headers: () => ({ ...own(), ...call?.headers }),
+                fetch: doFetch,
+            });
+            try {
+                const page = await source.read(criteria, signal);
+                return {
+                    ...page,
+                    meta: page.meta ?? (await definitionAt(`${base}${route}`, "get", page.version)),
+                };
+            }
+            catch (error) {
+                if (error instanceof RestError)
+                    throw new TransportError(route, error.status, error.problem, undefined);
+                throw error;
+            }
+        },
+        async read(route, signal, call) {
+            return (await get(route, urlOf(base, route), signal, undefined, call));
+        },
+        async one(route, signal, call) {
+            const answer = (await get(route, urlOf(base, route), signal, undefined, call));
+            const own = Object.keys(answer).filter((key) => !ENVELOPE.has(key));
+            const [key] = own;
+            if (own.length !== 1 || key === undefined)
+                throw new TransportError(route, 200, null, `${route} answered ${own.length} fields of its own (${own.join(", ")}); a record answers one`);
+            return {
+                record: answer[key],
+                meta: await definitionAt(urlOf(base, route), "get", answer["model_version"]),
+                dropped: answer["dropped"] ?? [],
+                draft: answer["draft"] ?? null,
+            };
+        },
+        async send(method, route, body, signal, sending) {
+            return (await get(route, urlOf(base, route), signal, { method, body, key: sending?.idempotencyKey }, sending));
+        },
+    };
+}

package/dist/client/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `Idempotency-Key` of a gesture: one per thing a person meant to do, the SAME one while
+ * that thing is retried.
+ *
+ * Context: a Command that got no answer — the network dropped, a proxy answered 502 — may have
+ * run. Sending it again with a new key could pay twice; with the same key the server answers
+ * what it already did (sincpro_framework's `@idempotency`). So a key lives until the server
+ * gives a definite answer: done, or refused for a reason a retry does not change. Changing the
+ * body is a different gesture, and gets a new key — the server refuses a key that comes back
+ * with another payload.
+ *
+ *     const keys = retryKeys();
+ *     const key = keys.keyFor(body);          // the same while the previous one went unanswered
+ *     try { await send(…, { idempotencyKey: key }); keys.settle(null); }
+ *     catch (error) { keys.settle(error); }   // kept when nobody knows what happened
+ */
+export type RetryKeys = {
+    keyFor: (body: unknown) => string;
+    /** What the last attempt ended in: `null` when it was answered. */
+    settle: (error: unknown) => void;
+};
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export declare function unanswered(error: unknown): boolean;
+export declare function retryKeys(make?: () => string): RetryKeys;

package/dist/client/retry.js

@@ -0,0 +1,25 @@
+import { TransportError } from "./transport.js";
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export function unanswered(error) {
+    if (!(error instanceof TransportError))
+        return true;
+    if (error.status === null || error.status >= 500)
+        return true;
+    // The same key is still running elsewhere: retry once it completes, with that key.
+    return error.problem?.kind === "in_progress";
+}
+export function retryKeys(make = () => globalThis.crypto.randomUUID()) {
+    let pending = null;
+    return {
+        keyFor: (body) => {
+            const sent = JSON.stringify(body ?? null);
+            if (pending === null || pending.body !== sent)
+                pending = { body: sent, key: make() };
+            return pending.key;
+        },
+        settle: (error) => {
+            if (error === null || !unanswered(error))
+                pending = null;
+        },
+    };
+}

package/dist/client/transport.d.ts

@@ -0,0 +1,89 @@
+import type { Criteria, Dropped, Meta, Page, Problem } from "@sincpro/criteria";
+/**
+ * The one seam between this package and a server.
+ *
+ * Context: a list and a record are the same two questions whatever the wire is — «a page of
+ * these, under this criteria» and «this one». REST today; JSON-RPC and gRPC are the other
+ * wires sincpro_framework serves. Each of those is
+ * one adapter implementing this, and nothing above it changes. A route is a string the adapter
+ * understands: a path for REST, a method for RPC.
+ *
+ * Every adapter throws `TransportError` for a refusal, so a screen explains a failure once
+ * whichever wire it came over.
+ */
+export interface Transport {
+    /** A page of records under the criteria. */
+    list<T>(route: string, criteria: Criteria<T>, signal?: AbortSignal, options?: CallOptions): Promise<Page<T>>;
+    /** One record, with the definition of its model. */
+    one<T>(route: string, signal?: AbortSignal, options?: CallOptions): Promise<One<T>>;
+    /** A Command — a write, an action, a preview: `method` and a JSON body, its answer back. */
+    send<T>(method: Method, route: string, body: unknown, signal?: AbortSignal, options?: SendOptions): Promise<T>;
+    /**
+     * A read that is neither a page nor one record — a Query of the context's own, `GET /me` —:
+     * the route with its parameters already in it (`listRoute`), its answer as it came. Optional,
+     * so a transport written before it keeps compiling; call it through `readRoute`.
+     */
+    read?<T>(route: string, signal?: AbortSignal, options?: CallOptions): Promise<T>;
+}
+/**
+ * A read through `transport.read`, or the reason it cannot be: a transport that has no `read`
+ * is said so by name, never a `TypeError` from somewhere inside a screen.
+ */
+export declare function readRoute<T>(transport: Transport, route: string, signal?: AbortSignal, options?: CallOptions): Promise<T>;
+export type Method = "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * How a Command travels besides its body.
+ *
+ * Context: sincpro_framework runs a Command declared `@idempotency` once per key (REST: the
+ * `Idempotency-Key` header; 400 `IDEMPOTENCY_KEY_MISSING` without it) and answers a repeat with
+ * the first answer. That is what makes «retry» safe after a request that got no answer: the
+ * server may have created the invoice, and the same key cannot create it twice.
+ */
+export type SendOptions = CallOptions & {
+    /** One per gesture, kept while it is retried — `retryKeys()`. */
+    idempotencyKey?: string;
+};
+/**
+ * What one call carries besides its question: headers of that call alone.
+ *
+ * Context: the trace and the context of the use case that asked travel with each request
+ * (`traceparent`, `sincpro-context`) — and two use cases run at once, so they cannot be the
+ * transport's own headers. A transport bound to a use case's execution (`bindTransport`) writes
+ * them here; a transport that has nowhere to send headers ignores them.
+ */
+export type CallOptions = {
+    headers?: Readonly<Record<string, string>>;
+};
+/** One record as sincpro_framework answers it (`ResponseRecord`): the record, its model. */
+export type One<T> = {
+    record: T;
+    meta: Meta | null;
+    dropped: Dropped[];
+    /** What this caller kept of an edit between requests (sincpro_framework `Drafts`). */
+    draft: Draft | null;
+};
+/** A kept edit: the values typed, the version of the draft, the record version it started on. */
+/**
+ * The caller's draft of a record (sincpro_framework's `DraftState`): the version the next edit
+ * names, the stored version it started from, and whether the record moved on since (`stale`).
+ * `values` only when a server answers them apart from the record — sincpro_framework answers the
+ * record FROM the draft instead.
+ */
+export type Draft = {
+    values?: Record<string, unknown>;
+    version: number;
+    origin_version?: number;
+    kept_at?: string;
+    stale?: boolean;
+};
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export declare class TransportError extends Error {
+    readonly route: string;
+    readonly status: number | null;
+    readonly problem: Problem | null;
+    constructor(route: string, status: number | null, problem: Problem | null, message?: string);
+}

package/dist/client/transport.js

@@ -0,0 +1,26 @@
+/**
+ * A read through `transport.read`, or the reason it cannot be: a transport that has no `read`
+ * is said so by name, never a `TypeError` from somewhere inside a screen.
+ */
+export function readRoute(transport, route, signal, options) {
+    if (transport.read === undefined)
+        return Promise.reject(new Error(`this transport has no read(): it cannot ask GET ${route} — give it one`));
+    return transport.read(route, signal, options);
+}
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export class TransportError extends Error {
+    route;
+    status;
+    problem;
+    constructor(route, status, problem, message) {
+        super(message ?? problem?.detail ?? problem?.title ?? `${status ?? "no answer"} at ${route}`);
+        this.route = route;
+        this.status = status;
+        this.problem = problem;
+        this.name = "TransportError";
+    }
+}

package/dist/codegen/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/codegen/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { clientFileOf } from "./client.js";
+import { domainFileOf } from "./domain.js";
+import { entitiesFileOf } from "./entities.js";
+import { aliasOf } from "./names.js";
+/**
+ * `sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]` — what an
+ * application's `make client` runs, once per bounded context, over the client contract
+ * sincpro_framework exported (`export-client-contract`):
+ *
+ * - `domain.ts`: the DTOs, only types;
+ * - `client.ts`: every operation as data, and `clientOf(transport)`;
+ * - `entities.ts`: an `entity<T, C>()` per model a screen can list;
+ * - `contract.json`: the snapshot they were written from, for `metasOf`.
+ *
+ * A bare metamodel (`export_metamodel`, no bindings) writes `domain.ts` and `contract.json` only.
+ *
+ * Context: it writes only into `--out`, and the same bytes for the same contract, so `make
+ * verify-client` regenerates and fails on any difference. The folder is the generator's: keep
+ * it out of the application's prettier and eslint, or a formatter rewrites what was generated.
+ */
+const USAGE = "usage: sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]";
+/** JSON with every key sorted: the snapshot reads the same however the server ordered it. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, canonical(value[key])]));
+}
+/** The command, its source and its flags — or `undefined` when they do not read as usage says. */
+function parsed(args) {
+    const [command, source, ...rest] = args;
+    if (command !== "generate" || source === undefined)
+        return undefined;
+    const flags = new Map();
+    for (let at = 0; at < rest.length; at += 2) {
+        const flag = rest[at];
+        const value = rest[at + 1];
+        if (flag === undefined || value === undefined || !flag.startsWith("--"))
+            return undefined;
+        flags.set(flag, value);
+    }
+    const out = flags.get("--out");
+    const known = new Set(["--out", "--domain", "--base"]);
+    if (out === undefined || [...flags.keys()].some((one) => !known.has(one)))
+        return undefined;
+    const domain = flags.get("--domain");
+    const base = flags.get("--base");
+    return {
+        source,
+        out,
+        options: {
+            ...(domain === undefined ? {} : { domain }),
+            ...(base === undefined ? {} : { base }),
+        },
+    };
+}
+function main(args) {
+    const asked = parsed(args);
+    if (asked === undefined) {
+        console.error(USAGE);
+        return 2;
+    }
+    const metamodel = JSON.parse(readFileSync(asked.source, "utf8"));
+    const files = { "domain.ts": domainFileOf(metamodel) };
+    if (metamodel.bindings !== undefined) {
+        files["client.ts"] = clientFileOf(metamodel, asked.options);
+        files["entities.ts"] = entitiesFileOf(metamodel, asked.options);
+    }
+    files["contract.json"] = `${JSON.stringify(canonical(metamodel), null, 2)}\n`;
+    mkdirSync(asked.out, { recursive: true });
+    for (const [name, source] of Object.entries(files))
+        writeFileSync(join(asked.out, name), source);
+    console.log(`✓ ${aliasOf(metamodel)} → ${asked.out} (${Object.keys(files).join(", ")})`);
+    return 0;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/codegen/client.d.ts

@@ -0,0 +1,14 @@
+import type { Metamodel } from "./metamodel.js";
+import { type GenerateOptions } from "./rest.js";
+/**
+ * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Every operation, by its local name, as data: identity, role, `query`, entities, targets
+ *    and the binding of each wire that publishes it.
+ * 2. Per operation REST reaches, how a transport calls it (`callOf`): a page, a record, a write
+ *    — or none, said in the client's own doc.
+ * 3. The routes of the writes, read once (`writeRoute`).
+ * Final: `clientOf(transport)`, a method per operation reached, named by `methodOf`; two with
+ *    one name are refused, naming both.
+ */
+export declare function clientFileOf(metamodel: Metamodel, options?: GenerateOptions): string;

package/dist/codegen/client.js

@@ -0,0 +1,180 @@
+import { aliasOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "./names.js";
+import { ownerOf, restOf, WRITES, } from "./rest.js";
+/**
+ * The client of a bounded context as TypeScript: every operation as data, and a method for each
+ * one REST reaches the way a `Transport` sends — over `@sincpro/client-framework`, so a script,
+ * a test or a hook of its own calls the service typed, with no screen.
+ *
+ * Context: a method only writes down the route the contract published and hands the call to the
+ * transport, which keeps the rules — the `Idempotency-Key`, the `Problem`, the model's version.
+ * A GET is a page (`list`), one record (`one`), or — a Query of the context's own, `GET /me` —
+ * a read of its answer as it came (`readRoute`, over a transport that has `read`). A GET's
+ * keys in its path are required parameters; every other field is an optional one.
+ */
+/** A search's fields a page asks with, not the screen: the criteria, and its cursor inside it. */
+const PAGED = new Set(["criteria", "cursor"]);
+/** A GET's parameters: the path's keys, and the rest of its input but what a page asks with. */
+function askedOf(operation, rest, paged) {
+    const path = [...rest.fields].sort();
+    const query = Object.keys(operation.input.properties ?? {})
+        .filter((one) => !path.includes(one) && !(paged && PAGED.has(one)))
+        .sort();
+    return { path, query };
+}
+function callOf(metamodel, operation, rest) {
+    if (rest === undefined)
+        return { kind: "none", why: "REST does not publish it" };
+    if (WRITES.has(rest.method))
+        return { kind: "send" };
+    const owner = ownerOf(metamodel, operation);
+    if (operation.role === "search" && owner !== undefined && owner in metamodel.models)
+        return { kind: "list", entity: owner, ...askedOf(operation, rest, true) };
+    const field = owner === undefined ? undefined : operation.targets[owner];
+    const record = rest.fields.length === 1 && rest.fields[0] === field;
+    if (operation.role === "get" && owner !== undefined && field !== undefined && record)
+        return { kind: "one", entity: owner, field };
+    // Any other GET — a Query of the context's own, `GET /me` — is read as it answers.
+    return { kind: "read", ...askedOf(operation, rest, false) };
+}
+/** A parameter list's TypeScript: the path's keys required, the rest optional, all as text. */
+function paramsOf(asked) {
+    const union = (names) => names.map((one) => JSON.stringify(one)).join(" | ");
+    if (asked.path.length === 0 && asked.query.length === 0)
+        return { signature: "", route: (path) => JSON.stringify(path) };
+    const required = asked.path.length === 0 ? "" : `Readonly<Record<${union(asked.path)}, string>>`;
+    const optional = asked.query.length === 0 ? "" : `Partial<Record<${union(asked.query)}, string>>`;
+    const type = [required, optional].filter((one) => one !== "").join(" & ");
+    return {
+        signature: `params${asked.path.length === 0 ? "?" : ""}: ${type}`,
+        route: (path) => `listRoute(${JSON.stringify(path)}, params)`,
+    };
+}
+/** The data of one operation: what it is, and how each wire reaches it. */
+function dataOf(metamodel, identity, operation, rest) {
+    const lines = [
+        `    identity: ${JSON.stringify(identity)},`,
+        `    role: ${JSON.stringify(operation.role)},`,
+        `    query: ${operation.query},`,
+        `    entities: ${JSON.stringify(operation.entities)},`,
+        `    targets: ${recordLiteral(operation.targets)},`,
+    ];
+    if (rest !== undefined)
+        lines.push(`    rest: { method: ${JSON.stringify(rest.method)}, path: ${JSON.stringify(rest.path)} },`);
+    const rpc = metamodel.bindings?.rpc?.[identity];
+    if (rpc !== undefined)
+        lines.push(`    rpc: { method: ${JSON.stringify(rpc.method)} },`);
+    const grpc = metamodel.bindings?.grpc?.[identity];
+    if (grpc !== undefined)
+        lines.push(`    grpc: { method: ${JSON.stringify(grpc.method)} },`);
+    const mcp = metamodel.bindings?.mcp?.[identity];
+    if (mcp !== undefined)
+        lines.push(`    mcp: { tool: ${JSON.stringify(mcp.tool)} },`);
+    return `  ${localOf(metamodel, identity)}: {\n${lines.join("\n")}\n  },`;
+}
+function methodSourceOf(local, method, call, rest, doc) {
+    if (call.kind === "list") {
+        const entity = `dto.${identifierOf(call.entity)}`;
+        const params = paramsOf(call);
+        const signature = params.signature === "" ? "" : `, ${params.signature}`;
+        return `${doc}    ${method}: (criteria: Criteria<${entity}>${signature}) =>\n      transport.list<${entity}>(${params.route(rest.path)}, criteria),`;
+    }
+    if (call.kind === "read") {
+        const params = paramsOf(call);
+        return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${local}Answer>(transport, ${params.route(rest.path)}),`;
+    }
+    if (call.kind === "one") {
+        const path = rest.path.replace(`{${call.field}}`, "${encodeURIComponent(id)}");
+        return `${doc}    ${method}: (id: string) =>\n      transport.one<dto.${identifierOf(call.entity)}>(\`${path}\`),`;
+    }
+    const id = rest.fields.includes("id")
+        ? "body.id === undefined ? undefined : String(body.id)"
+        : "undefined";
+    return [
+        `${doc}    ${method}: (body: dto.${local}, options?: SendOptions) =>`,
+        `      transport.send<dto.${local}Answer>(`,
+        `        ${JSON.stringify(rest.method)},`,
+        `        pathFor(routes.${method}, ${id}, body),`,
+        `        body,`,
+        `        undefined,`,
+        `        options,`,
+        `      ),`,
+    ].join("\n");
+}
+/**
+ * The TypeScript of the client of `metamodel`, as the text of one file next to its `domain.ts`.
+ *
+ * 1. Every operation, by its local name, as data: identity, role, `query`, entities, targets
+ *    and the binding of each wire that publishes it.
+ * 2. Per operation REST reaches, how a transport calls it (`callOf`): a page, a record, a write
+ *    — or none, said in the client's own doc.
+ * 3. The routes of the writes, read once (`writeRoute`).
+ * Final: `clientOf(transport)`, a method per operation reached, named by `methodOf`; two with
+ *    one name are refused, naming both.
+ */
+export function clientFileOf(metamodel, options = {}) {
+    const claim = claimed();
+    const operations = sorted(metamodel.operations);
+    const data = [];
+    const routes = [];
+    const methods = [];
+    const unreached = [];
+    let lists = false;
+    let paged = false;
+    let reads = false;
+    let sends = false;
+    for (const [identity, operation] of operations) {
+        const local = localOf(metamodel, identity);
+        const rest = restOf(metamodel, identity, options);
+        data.push(dataOf(metamodel, identity, operation, rest));
+        const call = callOf(metamodel, operation, rest);
+        if (call.kind === "none" || rest === undefined) {
+            unreached.push(`\`${local}\`: ${call.kind === "none" ? call.why : ""}.`);
+            continue;
+        }
+        const method = methodOf(local);
+        claim(method, `operation ${identity}`);
+        const doc = docOf([operation.description, deprecationOf(metamodel, operation)], "    ");
+        methods.push(methodSourceOf(local, method, call, rest, doc));
+        if (call.kind === "list" || call.kind === "read") {
+            paged ||= call.kind === "list";
+            reads ||= call.kind === "read";
+            lists ||= call.path.length + call.query.length > 0;
+        }
+        if (call.kind === "send") {
+            sends = true;
+            routes.push(`  ${method}: writeRoute(${JSON.stringify(`${rest.method} ${rest.path}`)}),`);
+        }
+    }
+    const core = [
+        "bindable",
+        ...(lists ? ["listRoute"] : []),
+        ...(sends ? ["pathFor"] : []),
+        ...(reads ? ["readRoute"] : []),
+        ...(sends ? ["type SendOptions"] : []),
+        "type Transport",
+        ...(sends ? ["writeRoute"] : []),
+    ];
+    const imports = [
+        ...(paged ? ['import type { Criteria } from "@sincpro/criteria";'] : []),
+        `import { ${core.join(", ")} } from "${FRAMEWORK}";`,
+        "",
+        `import type * as dto from "${DOMAIN_MODULE}";`,
+    ].join("\n");
+    const client = [
+        "/**",
+        ` * «${aliasOf(metamodel)}» over a transport: a method for each operation REST reaches as a`,
+        " * page, a record, a read of its own or a write. Used by a Feature, each request carries the",
+        " * trace and the context of the use case that sent it (`bindable`).",
+        ...(unreached.length === 0
+            ? []
+            : [" *", " * Without a method here:", ...unreached.map((one) => ` * - ${one}`)]),
+        " */",
+    ].join("\n");
+    return `${[
+        headerOf("The client", metamodel),
+        imports,
+        `/** Every operation of «${aliasOf(metamodel)}», as data: what it is, and how each wire reaches it. */\nexport const operations = {\n${data.join("\n")}\n} as const;`,
+        ...(routes.length === 0 ? [] : [`const routes = {\n${routes.join("\n")}\n};`]),
+        `${client}\nexport function clientOf(transport: Transport) {\n  return bindable(transport, (transport) => ({\n${methods.join("\n")}\n  }));\n}`,
+    ].join("\n\n")}\n`;
+}

package/dist/codegen/domain.d.ts

@@ -0,0 +1,14 @@
+import type { Metamodel } from "./metamodel.js";
+/**
+ * The TypeScript of every DTO of `metamodel`, as the text of one file.
+ *
+ * 1. The models, by name: an entity's contract, a related model by its own name.
+ * 2. Each operation, by its local name (its identity without `<context>.`): its input as
+ *    `<Name>` and its answer as `<Name>Answer`.
+ * 3. The shared definitions those reach — and the ones those reach, until none is new —, but
+ *    never one a package of the stack already types (`Criteria`).
+ * Final: a header that says where it came from and not to edit it, the imports, then models,
+ *    definitions and operations, each sorted by name; two of them with one TypeScript name are
+ *    refused, naming both.
+ */
+export declare function domainFileOf(metamodel: Metamodel): string;