@sincpro/client-framework 0.4.0 → 0.6.0

package/dist/codegen/check.js

@@ -0,0 +1,195 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+const LAYERS = new Set([
+    "generated",
+    "domain",
+    "adapters",
+    "services",
+    "infrastructure",
+    "components",
+    "entrypoints",
+]);
+/**
+ * `domains/sales/services/close.ts` → the bounded context `sales`, the layer `services` — wherever
+ * the `domains/` folder is (`src/domains/…`, a workspace's `domains/sales/src/services/…`).
+ */
+export function placeOf(path) {
+    const parts = path.split(/[\\/]/).filter((one) => one !== "");
+    const start = parts[0] === "src" ? 1 : 0;
+    if (parts[start] === "entrypoints")
+        return { kind: "entrypoint" };
+    const at = parts.indexOf("domains");
+    const context = at === -1 ? undefined : parts[at + 1];
+    if (context === undefined || parts.length < at + 3)
+        return { kind: "other" };
+    // A bounded context that is a package of its own keeps its code under `src/`.
+    const rest = parts.slice(at + 2);
+    const inside = rest[0] === "src" && rest.length > 1 ? rest.slice(1) : rest;
+    const first = inside[0] ?? "";
+    const index = inside.length === 1 && /^index\.(ts|tsx|js|jsx|mts)$/.test(first);
+    return { kind: "context", context, layer: LAYERS.has(first) ? first : null, index };
+}
+const REACT = /^(react|react-dom|react-native)(\/|$)/;
+const DRAWING = /^@sincpro\/(web-ui|web-composer)(\/|$)/;
+const COMPOSER = /^@sincpro\/web-composer(\/|$)/;
+const ROUTER = /^(react-router|react-router-dom|@tanstack\/react-router|next\/navigation|next\/router|expo-router)(\/|$)/;
+/** web-framework draws; only its `core` is plain logic a service may use. */
+const SCREENS = /^@sincpro\/web-framework(?!\/core(\/|$))(\/|$)/;
+const PLAIN = new Set(["generated", "domain", "adapters", "services"]);
+/** Within a bounded context, what each layer never imports of its own. */
+const NEVER_OWN = {
+    generated: ["adapters", "services", "infrastructure", "components", "entrypoints"],
+    domain: ["adapters", "services", "infrastructure", "components", "entrypoints"],
+    adapters: ["services", "components", "entrypoints"],
+    services: ["components", "entrypoints"],
+    infrastructure: ["components", "entrypoints"],
+};
+/**
+ * Why `from` may not import `specifier`, which resolves to `to` (`null`: a package), or nothing
+ * when it may.
+ */
+export function violationOf(from, specifier, to) {
+    if (to === null) {
+        if (from.kind !== "context" || from.layer === null)
+            return undefined;
+        if (PLAIN.has(from.layer) &&
+            (REACT.test(specifier) || DRAWING.test(specifier) || SCREENS.test(specifier)))
+            return `${from.layer}/ is plain logic: it never imports a screen's library (React, web-ui, composer, web-framework but its core)`;
+        if (from.layer === "components" && (COMPOSER.test(specifier) || ROUTER.test(specifier)))
+            return "a component never decides where things open: no composer, no router";
+        return undefined;
+    }
+    // The application's entrypoints compose everything; nothing imports them back.
+    if (to.kind === "entrypoint")
+        return from.kind === "entrypoint"
+            ? undefined
+            : "nothing imports the application's entrypoints";
+    if (to.kind !== "context")
+        return undefined;
+    // Outside the bounded contexts (the entrypoints, `main.tsx`, a `lib/`): only their index.ts.
+    if (from.kind !== "context")
+        return to.context === "common" || to.index
+            ? undefined
+            : `outside a bounded context, it is used through its index.ts, never its insides («${to.context}»)`;
+    if (from.context === "common")
+        return to.context === "common" ? undefined : "common never imports a bounded context";
+    if (to.context === "common")
+        return undefined;
+    if (to.context === from.context) {
+        const never = from.layer === null ? undefined : NEVER_OWN[from.layer];
+        return to.layer !== null && never?.includes(to.layer) === true
+            ? `${from.layer}/ never imports its own ${to.layer}/`
+            : undefined;
+    }
+    if (to.index && from.layer === "infrastructure")
+        return undefined;
+    return to.index
+        ? `another bounded context («${to.context}») is a dependency: added in infrastructure/, never imported here`
+        : `a bounded context never imports another's insides («${to.context}»): only its index.ts, from infrastructure/`;
+}
+function sources(root) {
+    const found = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (entry.name === "node_modules" || entry.name.startsWith("."))
+            continue;
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            found.push(...sources(path));
+        else if (/\.(ts|tsx|mts|cts|js|jsx)$/.test(entry.name) && !entry.name.endsWith(".d.ts"))
+            found.push(path);
+    }
+    return found;
+}
+/** What stops the check before it starts: no root, no config, a config that does not parse. */
+export class CheckError extends Error {
+}
+/**
+ * The compiler options the application resolves with: its config's, and those of every config it
+ * references — Vite writes `files: []` in `tsconfig.json` and keeps its aliases in
+ * `tsconfig.app.json`.
+ */
+function optionsOf(ts, path, seen) {
+    if (seen.has(path))
+        return [];
+    seen.add(path);
+    const read = ts.readConfigFile(path, ts.sys.readFile);
+    if (read.error !== undefined)
+        throw new CheckError(`${path}: ${ts.flattenDiagnosticMessageText(read.error.messageText, " ")}`);
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(path), undefined, path);
+    // «No inputs were found» is what a config of references only says: not an error here.
+    const broken = parsed.errors.find((one) => one.category === ts.DiagnosticCategory.Error && one.code !== 18003);
+    if (broken !== undefined)
+        throw new CheckError(`${path}: ${ts.flattenDiagnosticMessageText(broken.messageText, " ")}`);
+    return [
+        parsed.options,
+        ...(parsed.projectReferences ?? []).flatMap((one) => optionsOf(ts, ts.resolveProjectReferencePath(one), seen)),
+    ];
+}
+/** A style, an image, a font, data: what a bundler loads and TypeScript does not resolve. */
+const ASSET = /\.(css|scss|sass|less|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|json|md|mdx)(\?.*)?$/;
+/** `@acme/ventas`, `ventas` — a package named whole, never a path inside it. */
+const BARE = /^(@[^/]+\/)?[^/.@][^/]*$/;
+/**
+ * Every import under `root` that breaks a rule, resolved by the application's own TypeScript and
+ * `tsconfig` (its path aliases and its references included). An alias that does not resolve is a
+ * break too — read as a package it would switch every rule off.
+ */
+export async function checkImports(root, options = {}) {
+    if (!existsSync(root))
+        throw new CheckError(`${root} does not exist: say where the application's code is (--root)`);
+    const { default: ts } = await import("typescript");
+    if (options.tsconfig !== undefined && !ts.sys.fileExists(options.tsconfig))
+        throw new CheckError(`${options.tsconfig} does not exist`);
+    const configPath = options.tsconfig ?? ts.findConfigFile(root, ts.sys.fileExists);
+    const compilers = configPath === undefined ? [{}] : optionsOf(ts, configPath, new Set());
+    const aliases = compilers
+        .flatMap((one) => Object.keys(one.paths ?? {}))
+        .map((pattern) => pattern.replace(/\*.*$/, ""))
+        .filter((prefix) => prefix !== "");
+    const own = (path) => {
+        const from = relative(root, path);
+        return !from.startsWith("..") && !from.split(sep).includes("node_modules");
+    };
+    const violations = [];
+    for (const file of sources(root)) {
+        const name = relative(root, file).split(sep).join("/");
+        const from = placeOf(name);
+        for (const { fileName: specifier } of ts.preProcessFile(readFileSync(file, "utf8"), true, true).importedFiles) {
+            if (ASSET.test(specifier))
+                continue;
+            // The first config that finds it inside the application, else any that finds it.
+            let resolved;
+            for (const compiler of compilers) {
+                const found = ts.resolveModuleName(specifier, file, compiler, ts.sys).resolvedModule;
+                if (found === undefined)
+                    continue;
+                resolved ??= found;
+                if (own(found.resolvedFileName)) {
+                    resolved = found;
+                    break;
+                }
+            }
+            if (resolved === undefined && aliases.some((prefix) => specifier.startsWith(prefix))) {
+                violations.push({
+                    file: name,
+                    imports: specifier,
+                    why: "it does not resolve: an alias of the application that no tsconfig finds",
+                });
+                continue;
+            }
+            const inside = resolved !== undefined && own(resolved.resolvedFileName);
+            let to = inside
+                ? placeOf(relative(root, resolved.resolvedFileName).split(sep).join("/"))
+                : specifier.startsWith(".")
+                    ? { kind: "other" }
+                    : null;
+            // A bounded context that is a package, named whole (`@acme/ventas`): its index.
+            if (to?.kind === "context" && BARE.test(specifier))
+                to = { ...to, index: true };
+            const why = violationOf(from, specifier, to);
+            if (why !== undefined)
+                violations.push({ file: name, imports: specifier, why });
+        }
+    }
+    return violations;
+}

package/dist/codegen/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CheckError, checkImports } from "./check.js";
 import { clientFileOf } from "./client.js";
 import { domainFileOf } from "./domain.js";
 import { entitiesFileOf } from "./entities.js";
 import { aliasOf } from "./names.js";
+import { scaffoldFilesOf } from "./scaffold.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
@@ -21,7 +23,11 @@ import { aliasOf } from "./names.js";
  * 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>]";
+const USAGE = [
+    "usage: sincpro-client generate <contract.json> --out <dir> [--domain <name>] [--base <path>]",
+    "       sincpro-client scaffold <contract.json> --out <dir> [--transport <module>]",
+    "       sincpro-client check [--root src] [--tsconfig tsconfig.json]",
+].join("\n");
 /** JSON with every key sorted: the snapshot reads the same however the server ordered it. */
 function canonical(value) {
     if (Array.isArray(value))
@@ -35,7 +41,7 @@ function canonical(value) {
 /** 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)
+    if ((command !== "generate" && command !== "scaffold") || source === undefined)
         return undefined;
     const flags = new Map();
     for (let at = 0; at < rest.length; at += 2) {
@@ -46,20 +52,73 @@ function parsed(args) {
         flags.set(flag, value);
     }
     const out = flags.get("--out");
-    const known = new Set(["--out", "--domain", "--base"]);
+    const known = new Set(command === "generate" ? ["--out", "--domain", "--base"] : ["--out", "--transport"]);
     if (out === undefined || [...flags.keys()].some((one) => !known.has(one)))
         return undefined;
     const domain = flags.get("--domain");
     const base = flags.get("--base");
     return {
+        command,
         source,
         out,
         options: {
             ...(domain === undefined ? {} : { domain }),
             ...(base === undefined ? {} : { base }),
         },
+        transport: flags.get("--transport"),
     };
 }
+/** The skeleton, each file only when it is not there: what is there is the application's. */
+function scaffold(metamodel, out, transport) {
+    const files = scaffoldFilesOf(metamodel, transport === undefined ? {} : { transport });
+    const written = [];
+    const kept = [];
+    for (const [name, source] of Object.entries(files)) {
+        const path = join(out, name);
+        if (existsSync(path)) {
+            kept.push(name);
+            continue;
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, source);
+        written.push(name);
+    }
+    console.log(`✓ ${aliasOf(metamodel)} → ${out}: written ${written.join(", ") || "nothing"}${kept.length === 0 ? "" : `; kept, already yours: ${kept.join(", ")}`}`);
+    return 0;
+}
+/** The import rules (`codegen/check.ts`): every break said, and a failing exit when any. */
+async function check(args) {
+    const flags = new Map();
+    for (let at = 0; at < args.length; at += 2) {
+        const flag = args[at];
+        const value = args[at + 1];
+        if (flag === undefined ||
+            value === undefined ||
+            !["--root", "--tsconfig"].includes(flag)) {
+            console.error(USAGE);
+            return 2;
+        }
+        flags.set(flag, value);
+    }
+    const root = flags.get("--root") ?? "src";
+    const tsconfig = flags.get("--tsconfig");
+    let found;
+    try {
+        found = await checkImports(root, tsconfig === undefined ? {} : { tsconfig });
+    }
+    catch (error) {
+        if (!(error instanceof CheckError))
+            throw error;
+        console.error(`✘ ${error.message}`);
+        return 2;
+    }
+    for (const one of found)
+        console.error(`✘ ${root}/${one.file} imports "${one.imports}": ${one.why}`);
+    if (found.length > 0)
+        return 1;
+    console.log(`✓ ${root}: every import keeps the layers`);
+    return 0;
+}
 function main(args) {
     const asked = parsed(args);
     if (asked === undefined) {
@@ -67,6 +126,8 @@ function main(args) {
         return 2;
     }
     const metamodel = JSON.parse(readFileSync(asked.source, "utf8"));
+    if (asked.command === "scaffold")
+        return scaffold(metamodel, asked.out, asked.transport);
     const files = { "domain.ts": domainFileOf(metamodel) };
     if (metamodel.bindings !== undefined) {
         files["client.ts"] = clientFileOf(metamodel, asked.options);
@@ -79,4 +140,10 @@ function main(args) {
     console.log(`✓ ${aliasOf(metamodel)} → ${asked.out} (${Object.keys(files).join(", ")})`);
     return 0;
 }
-process.exitCode = main(process.argv.slice(2));
+const args = process.argv.slice(2);
+if (args[0] === "check")
+    void check(args.slice(1)).then((code) => {
+        process.exitCode = code;
+    });
+else
+    process.exitCode = main(args);

package/dist/codegen/client.js

@@ -1,4 +1,4 @@
-import { aliasOf, claimed, deprecationOf, docOf, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, localOf, methodOf, recordLiteral, sorted, } from "./names.js";
+import { aliasOf, answerOf, 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
@@ -7,17 +7,20 @@ import { ownerOf, restOf, WRITES, } from "./rest.js";
  *
  * 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
+ * A GET is a page (`list`), one record (`one`), a file (`export`: `downloadRoute`, its bytes as
+ * they arrive), 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"]);
+/** An export's fields its method takes apart: the criteria and the format. */
+const EXPORTED = new Set(["criteria", "cursor", "format"]);
 /** 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) {
+function askedOf(operation, rest, paged, apart = PAGED) {
     const path = [...rest.fields].sort();
     const query = Object.keys(operation.input.properties ?? {})
-        .filter((one) => !path.includes(one) && !(paged && PAGED.has(one)))
+        .filter((one) => !path.includes(one) && !(paged && apart.has(one)))
         .sort();
     return { path, query };
 }
@@ -29,6 +32,9 @@ function callOf(metamodel, operation, rest) {
     const owner = ownerOf(metamodel, operation);
     if (operation.role === "search" && owner !== undefined && owner in metamodel.models)
         return { kind: "list", entity: owner, ...askedOf(operation, rest, true) };
+    // An export answers bytes, never JSON: it is downloaded.
+    if (operation.role === "export" && owner !== undefined && owner in metamodel.models)
+        return { kind: "download", entity: owner, ...askedOf(operation, rest, true, EXPORTED) };
     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)
@@ -71,16 +77,25 @@ function dataOf(metamodel, identity, operation, rest) {
         lines.push(`    mcp: { tool: ${JSON.stringify(mcp.tool)} },`);
     return `  ${localOf(metamodel, identity)}: {\n${lines.join("\n")}\n  },`;
 }
-function methodSourceOf(local, method, call, rest, doc) {
+function methodSourceOf(local, answer, 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 === "download") {
+        const entity = `dto.${identifierOf(call.entity)}`;
+        const params = paramsOf(call);
+        // The path's keys are required, so they come first: a required parameter never follows an
+        // optional one.
+        const keys = params.signature === "" ? "" : `${params.signature.replace("params?:", "params:")}, `;
+        const given = params.signature === "" ? "" : ", params";
+        return `${doc}    ${method}: (${keys}criteria?: Criteria<${entity}>, format?: ExportFormat) =>\n      downloadRoute(transport, exportRoute(${JSON.stringify(rest.path)}, criteria, format${given})),`;
+    }
     if (call.kind === "read") {
         const params = paramsOf(call);
-        return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${local}Answer>(transport, ${params.route(rest.path)}),`;
+        return `${doc}    ${method}: (${params.signature}) =>\n      readRoute<dto.${answer}>(transport, ${params.route(rest.path)}),`;
     }
     if (call.kind === "one") {
         const path = rest.path.replace(`{${call.field}}`, "${encodeURIComponent(id)}");
@@ -91,7 +106,7 @@ function methodSourceOf(local, method, call, rest, doc) {
         : "undefined";
     return [
         `${doc}    ${method}: (body: dto.${local}, options?: SendOptions) =>`,
-        `      transport.send<dto.${local}Answer>(`,
+        `      transport.send<dto.${answer}>(`,
         `        ${JSON.stringify(rest.method)},`,
         `        pathFor(routes.${method}, ${id}, body),`,
         `        body,`,
@@ -122,6 +137,7 @@ export function clientFileOf(metamodel, options = {}) {
     let paged = false;
     let reads = false;
     let sends = false;
+    let downloads = false;
     for (const [identity, operation] of operations) {
         const local = localOf(metamodel, identity);
         const rest = restOf(metamodel, identity, options);
@@ -134,7 +150,11 @@ export function clientFileOf(metamodel, options = {}) {
         const method = methodOf(local);
         claim(method, `operation ${identity}`);
         const doc = docOf([operation.description, deprecationOf(metamodel, operation)], "    ");
-        methods.push(methodSourceOf(local, method, call, rest, doc));
+        methods.push(methodSourceOf(local, answerOf(metamodel, identity), method, call, rest, doc));
+        if (call.kind === "download") {
+            downloads = true;
+            paged = true;
+        }
         if (call.kind === "list" || call.kind === "read") {
             paged ||= call.kind === "list";
             reads ||= call.kind === "read";
@@ -147,6 +167,7 @@ export function clientFileOf(metamodel, options = {}) {
     }
     const core = [
         "bindable",
+        ...(downloads ? ["downloadRoute", "type ExportFormat", "exportRoute"] : []),
         ...(lists ? ["listRoute"] : []),
         ...(sends ? ["pathFor"] : []),
         ...(reads ? ["readRoute"] : []),

package/dist/codegen/domain.d.ts

@@ -4,7 +4,8 @@ import type { Metamodel } from "./metamodel.js";
  *
  * 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`.
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`), with
+ *    `<Name>Answer` kept as a deprecated alias — or as `<Name>Answer` when it has no name.
  * 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,

package/dist/codegen/domain.js

@@ -1,4 +1,4 @@
-import { claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
+import { answerOf, claimed, contextOf, deprecationOf, docOf, headerOf, identifierOf, keyOf, localOf, sorted, } from "./names.js";
 /**
  * The DTOs of a bounded context as TypeScript, out of the contract sincpro_framework exports:
  * a type per model, per shared definition a model or an operation reaches, and per operation's
@@ -20,7 +20,11 @@ const DEFINITIONS = "#/$defs/";
 /** A shared definition a package of the stack already types: imported, never written again. */
 const IMPORTED = {
     Criteria: { name: "Criteria", from: "@sincpro/criteria" },
+    Download: { name: "Download", from: "@sincpro/client-framework" },
+    EntityCollection: { name: "EntityCollection", from: "@sincpro/client-framework" },
 };
+/** A relation that holds several records: a reading answers it as a page of them. */
+const TO_MANY = new Set(["one2many", "many2many"]);
 /** The field types whose value is the record itself, not a key that names it. */
 const RELATIONAL = new Set(["many2one", "one2many", "many2many", "embedded"]);
 /** A related record: in an answer only when the read expands it. */
@@ -82,6 +86,29 @@ function optional(name, property, schema, record) {
         return EXPANDED.has(property["x-sincpro"]?.type ?? "");
     return !(schema.required ?? []).includes(name);
 }
+/**
+ * The records a to-many holds, when `property` is one — however the contract writes it: the
+ * collection a reading answers (`{items, count, cursor}`, sincpro_framework 3.33 on) or, before
+ * that, a bare array, which said less than the wire sent.
+ */
+function heldRecords(property) {
+    if (!TO_MANY.has(property["x-sincpro"]?.type ?? ""))
+        return undefined;
+    const held = property.properties?.["items"] ?? property;
+    return held.type === "array" ? held.items : undefined;
+}
+/**
+ * A property's TypeScript. A to-many inside a record is an `EntityCollection` of its records —
+ * a page with its count and cursor, as the read answers it — never an array, which would say the
+ * page is all there is.
+ */
+function propertyTypeOf(property, scope, depth, record) {
+    const records = record ? heldRecords(property) : undefined;
+    if (records === undefined)
+        return typeOf(property, scope, depth, record);
+    scope.imports.add("EntityCollection");
+    return `EntityCollection<${typeOf(records, scope, depth, record)}>`;
+}
 function objectOf(schema, scope, depth, record) {
     const properties = sorted(schema.properties ?? {});
     if (properties.length === 0) {
@@ -95,7 +122,7 @@ function objectOf(schema, scope, depth, record) {
     const lines = properties.map(([name, property]) => {
         const doc = docOf([property.description, keyNote(property)], pad);
         const mark = optional(name, property, schema, record) ? "?" : "";
-        return `${doc}${pad}${keyOf(name)}${mark}: ${typeOf(property, scope, depth + 1, record)};`;
+        return `${doc}${pad}${keyOf(name)}${mark}: ${propertyTypeOf(property, scope, depth + 1, record)};`;
     });
     return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
 }
@@ -133,6 +160,13 @@ function typeOf(schema, scope, depth, record) {
                 : objectOf(schema, scope, depth, record);
     }
 }
+/** What a streamed answer is on the client — an export's bytes (`Download`) —, else nothing. */
+function streamed(output, scope) {
+    if (output["x-sincpro-streamed"] === undefined)
+        return undefined;
+    scope.imports.add("Download");
+    return "Download";
+}
 /** What the server says of an operation: its words, then what it is, for whom, on which field. */
 function operationDoc(metamodel, local, operation) {
     const runsOn = sorted(operation.targets).map(([entity, field]) => `\`${entity}\` in \`${field}\``);
@@ -150,7 +184,8 @@ function operationDoc(metamodel, local, operation) {
  *
  * 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`.
+ *    `<Name>` and its answer by the backend's own name for it (`answerOf`: `ResponseX`), with
+ *    `<Name>Answer` kept as a deprecated alias — or as `<Name>Answer` when it has no name.
  * 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,
@@ -165,15 +200,28 @@ export function domainFileOf(metamodel) {
         claim(identifierOf(name), `model ${name}`);
         return `${docOf([schema.description], "")}export type ${identifierOf(name)} = ${typeOf(schema, scope, 0, true)};`;
     });
+    // A Response two Commands share is written once, under the first that answers with it.
+    const answered = new Set();
     const operations = sorted(metamodel.operations).flatMap(([identity, operation]) => {
         const local = localOf(metamodel, identity);
+        const named = answerOf(metamodel, identity);
         claim(local, `operation ${identity}`);
-        claim(`${local}Answer`, `the answer of ${identity}`);
-        const answer = operation.output === null ? "unknown" : typeOf(operation.output, scope, 0, false);
-        return [
+        const answer = operation.output === null
+            ? "unknown"
+            : (streamed(operation.output, scope) ?? typeOf(operation.output, scope, 0, false));
+        const written = [
             `${operationDoc(metamodel, local, operation)}export type ${local} = ${typeOf(operation.input, scope, 0, false)};`,
-            `/** What \`${local}\` answers. */\nexport type ${local}Answer = ${answer};`,
         ];
+        if (!answered.has(named)) {
+            answered.add(named);
+            claim(named, `the answer of ${identity}`);
+            written.push(`/** What \`${local}\` answers. */\nexport type ${named} = ${answer};`);
+        }
+        if (named !== `${local}Answer`) {
+            claim(`${local}Answer`, `the old name of the answer of ${identity}`);
+            written.push(`/** @deprecated The backend calls it \`${named}\`: use that name. */\nexport type ${local}Answer = ${named};`);
+        }
+        return written;
     });
     const written = new Map();
     for (let pending = [...scope.reached]; pending.length > 0;) {
@@ -187,9 +235,14 @@ export function domainFileOf(metamodel) {
         claim(identifierOf(name), `definition ${name}`);
         return written.get(name);
     });
-    const imports = [...scope.imports].sort().map((name) => {
+    // One line per package, its names sorted.
+    const byPackage = new Map();
+    for (const name of [...scope.imports].sort()) {
         const imported = IMPORTED[name];
-        return `import type { ${imported.name} } from "${imported.from}";`;
-    });
+        byPackage.set(imported.from, [...(byPackage.get(imported.from) ?? []), imported.name]);
+    }
+    const imports = [...byPackage.keys()]
+        .sort()
+        .map((from) => `import type { ${byPackage.get(from).join(", ")} } from "${from}";`);
     return `${[headerOf("The DTOs", metamodel), ...(imports.length === 0 ? [] : [imports.join("\n")]), ...models, ...shared, ...operations].join("\n\n")}\n`;
 }

package/dist/codegen/entities.d.ts

@@ -5,7 +5,8 @@ import { type GenerateOptions } from "./rest.js";
  *
  * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
  *    several) — none, and the model gets no entity, said in the file's own doc.
- * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`, and its
+ *    `export` — every record of a criteria as a file — by its path.
  * 3. Every write of role `command` that concerns it: with `target` when its body names the
  *    record, as it is when it creates one; its body typed without that field.
  * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of

package/dist/codegen/entities.js

@@ -1,5 +1,5 @@
 import { entityKeyOf } from "../client/contract.js";
-import { aliasOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
+import { aliasOf, answerOf, claimed, DOMAIN_MODULE, FRAMEWORK, headerOf, identifierOf, isEntity, localOf, methodOf, pluralOf, sorted, } from "./names.js";
 import { ownerOf, restOf, WRITES, } from "./rest.js";
 /** The one operation of `role` for `entity` a transport can call, by `own` when there are many. */
 function oneOf(candidates, role) {
@@ -37,7 +37,14 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         const rest = restOf(metamodel, identity, options);
         return rest === undefined
             ? []
-            : [{ local: localOf(metamodel, identity), operation, rest }];
+            : [
+                {
+                    local: localOf(metamodel, identity),
+                    answer: answerOf(metamodel, identity),
+                    operation,
+                    rest,
+                },
+            ];
     });
     const reads = (role, method) => reached.filter((one) => one.operation.role === role &&
         method(one.rest.method) &&
@@ -54,10 +61,18 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
     const missing = [];
     const routes = [`  list: ${JSON.stringify(list.found.rest.path)},`];
     const one = oneOf(reads("get", isGet), "get");
+    const edit = oneOf(reads("edit", isWrite), "edit");
     if (one !== undefined && "found" in one) {
         const field = one.found.operation.targets[model];
+        // sincpro_framework's `Get` answers the caller's own draft only when asked (`draft`), and an
+        // entity edited through `Edit` keeps its drafts there: its record is read with them, or a
+        // draft kept on one visit never comes back on the next.
+        const drafts = edit !== undefined &&
+            "found" in edit &&
+            one.found.operation.input.properties?.["draft"]?.type === "boolean";
+        const path = `${recordPath(one.found.rest, field)}${drafts ? "?draft=true" : ""}`;
         if (field !== undefined && one.found.rest.fields.length === 1)
-            routes.push(`  one: ${JSON.stringify(recordPath(one.found.rest, field))},`);
+            routes.push(`  one: ${JSON.stringify(path)},`);
         else
             missing.push(`one: \`${one.found.local}\` is at ${one.found.rest.path}`);
     }
@@ -75,6 +90,13 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         const route = `${write.found.rest.method} ${recordPath(write.found.rest, field)}`;
         routes.push(`  ${role}: ${JSON.stringify(route)},`);
     }
+    const exported = oneOf(reads("export", isGet), "export");
+    if (exported !== undefined) {
+        if ("missing" in exported)
+            missing.push(`export: ${exported.missing}`);
+        else
+            routes.push(`  export: ${JSON.stringify(exported.found.rest.path)},`);
+    }
     const commands = reached.filter((one) => one.operation.role === "command" &&
         isWrite(one.rest.method) &&
         one.operation.entities.includes(model));
@@ -88,7 +110,7 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
         bodies.push(target === undefined
             ? `    ${method}: dto.${command.local};`
             : `    ${method}: Omit<dto.${command.local}, ${JSON.stringify(target)}>;`);
-        answers.push(`    ${method}: dto.${command.local}Answer;`);
+        answers.push(`    ${method}: dto.${command.answer};`);
         named.push(target === undefined
             ? `    ${method}: ${JSON.stringify(route)},`
             : `    ${method}: { route: ${JSON.stringify(route)}, target: ${JSON.stringify(target)} },`);
@@ -120,7 +142,8 @@ function entitySourceOf(metamodel, model, domain, options, claim) {
  *
  * 1. Per model, by name: the one `search` a transport reads for it (`own` when there are
  *    several) — none, and the model gets no entity, said in the file's own doc.
- * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`.
+ * 2. Its `get`, `edit` and `preview` the same way, the record's field written `{id}`, and its
+ *    `export` — every record of a criteria as a file — by its path.
  * 3. Every write of role `command` that concerns it: with `target` when its body names the
  *    record, as it is when it creates one; its body typed without that field.
  * Final: an `entity<T, C>()` per model listed, keyed `<domain>:<kind>`, and `entities`, all of