lambder 14.1.1 → 15.0.1

package/dist/build/generateApiFiles.d.ts

@@ -1,8 +1,9 @@
 import type { LambderModuleLocation } from "./moduleLocation.js";
-import { type LambderApiContractFileOptions } from "./writeApiContract.js";
+import type { LambderApiContractFileOptions } from "./writeApiContract.js";
 import { type LambderApiSignatureFileOptions } from "./writeApiSignatures.js";
 import { type LambderApiOptionsFileOptions } from "./writeApiOptions.js";
 import { type LambderApiGuardParamsFileOptions } from "./writeApiGuardParams.js";
+import { type LambderApiSchemasFileOptions } from "./writeApiSchemas.js";
 /** What a file's writer takes beyond where the instance is, which the app gives once for all its files. */
 type LambderAppFile<TOptions> = Omit<TOptions, "module" | "exportName" | "tsconfig" | "check">;
 /** One app: where its instance is, and which files it is written to. Each file is optional. */
@@ -21,21 +22,43 @@ export type LambderApiFilesApp = {
     options?: LambderAppFile<LambderApiOptionsFileOptions>;
     /** One file per guard whose parameters a browser needs (writeApiGuardParams). */
     guardParams?: readonly LambderAppFile<LambderApiGuardParamsFileOptions>[];
+    /** The input and output schemas as JSON Schema, for a mock to validate against in development (writeApiSchemas). */
+    schemas?: LambderAppFile<LambderApiSchemasFileOptions>;
 };
 /** The files generateApiFiles writes: every app's, by a name the output lines use. */
 export type LambderApiFilesConfig = {
     apps: Record<string, LambderApiFilesApp>;
 };
+/** How generateApiFiles runs. */
+export type LambderApiFilesOptions = {
+    /** Write nothing, and answer whether each file on disk is what its writer produces now. Default: false. */
+    check?: boolean;
+    /**
+     * The heap, in megabytes, of the Node process each contract is printed
+     * in (its --max-old-space-size). Reading a contract compiles the server,
+     * twice for a write that changes the file, which in a large app takes
+     * gigabytes; the process is started for that alone, so the heap is the
+     * printing's whatever the script's own is. Default: 8192.
+     */
+    contractHeapMegabytes?: number;
+};
 export type LambderApiFilesResult = {
     /** False when a check found a file stale, or a writer failed. */
     ok: boolean;
     /** What happened, per app and file, as lines to print. */
     lines: string[];
 };
+/**
+ * How the contract printing process reports: one line on stdout starting
+ * with this, then its report as JSON. The line, not the exit status, is the
+ * answer: a process that dies before it (out of heap, say) answered nothing.
+ */
+export declare const CONTRACT_REPORT_PREFIX = "lambder-api-contract-printed:";
 /**
  * Writes every file the config names, or with `check` writes nothing and
  * answers whether each one on disk is current. Paths are relative to the
- * working directory, as each writer takes them.
+ * working directory, as each writer takes them. Each contract is printed in
+ * a Node process of its own, with a heap of `contractHeapMegabytes`.
  *
  * ```ts
  * import { generateApiFiles } from "lambder/build";
@@ -54,7 +77,5 @@ export type LambderApiFilesResult = {
  * process.exit(result.ok ? 0 : 1);
  * ```
  */
-export declare const generateApiFiles: (config: LambderApiFilesConfig, options?: {
-    check?: boolean;
-}) => Promise<LambderApiFilesResult>;
+export declare const generateApiFiles: (config: LambderApiFilesConfig, options?: LambderApiFilesOptions) => Promise<LambderApiFilesResult>;
 export {};

package/dist/build/generateApiFiles.js

@@ -1,9 +1,22 @@
-import { writeApiContract } from "./writeApiContract.js";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
 import { writeApiSignatures } from "./writeApiSignatures.js";
 import { writeApiOptions } from "./writeApiOptions.js";
 import { writeApiGuardParams } from "./writeApiGuardParams.js";
-const APP_KEYS = ["module", "exportName", "tsconfig", "contract", "signatures", "options", "guardParams"];
-const FILE_KINDS = ["contract", "signatures", "options", "guardParams"];
+import { writeApiSchemas } from "./writeApiSchemas.js";
+const APP_KEYS = ["module", "exportName", "tsconfig", "contract", "signatures", "options", "guardParams", "schemas"];
+const FILE_KINDS = ["contract", "signatures", "options", "guardParams", "schemas"];
+const DEFAULT_CONTRACT_HEAP_MEGABYTES = 8192;
+/**
+ * How the contract printing process reports: one line on stdout starting
+ * with this, then its report as JSON. The line, not the exit status, is the
+ * answer: a process that dies before it (out of heap, say) answered nothing.
+ */
+export const CONTRACT_REPORT_PREFIX = "lambder-api-contract-printed:";
+/** The contract printing process's entry, beside this module in the build. */
+const CONTRACT_PRINTER_ENTRY = new URL("./contractPrinterProcess.js", import.meta.url);
+/** How much of a process's error output a failure repeats. */
+const STDERR_TAIL_LINES = 20;
 /** A config that names apps, each with its module and at least one file, and no key the generator does not read. */
 function assertConfig(config) {
     const apps = config?.apps;
@@ -19,7 +32,7 @@ function assertConfig(config) {
         if (!app.module)
             throw new Error(`generateApiFiles: the app "${name}" names no module to read its instance from.`);
         if (!FILE_KINDS.some((kind) => app[kind] !== undefined)) {
-            throw new Error(`generateApiFiles: the app "${name}" is written to no file; give it a contract, signatures, options or guardParams.`);
+            throw new Error(`generateApiFiles: the app "${name}" is written to no file; give it a contract, signatures, options, guardParams or schemas.`);
         }
     }
 }
@@ -35,10 +48,51 @@ const settle = async (label, write) => {
         return { ok: false, lines: [`✗ ${label} failed: ${reasons.join(": ") || String(err)}`] };
     }
 };
+/**
+ * writeApiContract in a Node process of its own, started with the heap given
+ * and none of this process's flags: the compiler loads no module of the app,
+ * so the script's loader is not needed there, and the heap the script runs
+ * with is not the printing's. Its result comes back as writeApiContract
+ * answers it, and what it throws is thrown here with the same messages, down
+ * the chain of causes, so a run reads the same as one in this process.
+ */
+const writeApiContractInOwnProcess = async (label, options, heapMegabytes) => {
+    const request = { ...options, module: options.module instanceof URL ? options.module.href : options.module };
+    const child = spawn(process.execPath, [`--max-old-space-size=${heapMegabytes}`, fileURLToPath(CONTRACT_PRINTER_ENTRY), JSON.stringify(request)], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
+    const ended = await new Promise((resolveEnd) => {
+        child.once("error", (error) => resolveEnd({ error }));
+        child.once("close", (status, signal) => resolveEnd({ status, signal }));
+    });
+    if ("error" in ended)
+        return { ok: false, lines: [`✗ ${label} failed: the process to print it in could not start: ${ended.error.message}`] };
+    const reportLine = stdout.split("\n").findLast((line) => line.startsWith(CONTRACT_REPORT_PREFIX));
+    if (reportLine === undefined) {
+        if (/JavaScript heap out of memory/i.test(stderr)) {
+            return { ok: false, lines: [`✗ ${label} failed: the process printing it ran out of its ${heapMegabytes} MB heap; raise contractHeapMegabytes`] };
+        }
+        const ending = ended.signal ? `signal ${ended.signal}` : `exit status ${ended.status ?? "none"}`;
+        return {
+            ok: false,
+            lines: [
+                `✗ ${label} failed: the process printing it ended without an answer (${ending})`,
+                ...stderr.trim().split("\n").filter(Boolean).slice(-STDERR_TAIL_LINES).map((line) => `  ${line}`),
+            ],
+        };
+    }
+    const report = JSON.parse(reportLine.slice(CONTRACT_REPORT_PREFIX.length));
+    if ("thrown" in report)
+        throw report.thrown.reduceRight((cause, message) => new Error(message, cause ? { cause } : undefined), undefined);
+    return report.result;
+};
 /**
  * Writes every file the config names, or with `check` writes nothing and
  * answers whether each one on disk is current. Paths are relative to the
- * working directory, as each writer takes them.
+ * working directory, as each writer takes them. Each contract is printed in
+ * a Node process of its own, with a heap of `contractHeapMegabytes`.
  *
  * ```ts
  * import { generateApiFiles } from "lambder/build";
@@ -60,6 +114,10 @@ const settle = async (label, write) => {
 export const generateApiFiles = async (config, options = {}) => {
     assertConfig(config);
     const check = options.check ?? false;
+    const contractHeapMegabytes = options.contractHeapMegabytes ?? DEFAULT_CONTRACT_HEAP_MEGABYTES;
+    if (!Number.isInteger(contractHeapMegabytes) || contractHeapMegabytes <= 0) {
+        throw new Error(`generateApiFiles: contractHeapMegabytes is ${String(contractHeapMegabytes)}; give the heap of the process each contract is printed in as a whole number of megabytes, such as ${DEFAULT_CONTRACT_HEAP_MEGABYTES}.`);
+    }
     const apps = Object.entries(config.apps);
     const runs = [];
     // The contracts first: they compile the app's sources and run none of
@@ -67,10 +125,11 @@ export const generateApiFiles = async (config, options = {}) => {
     for (const [name, app] of apps) {
         if (!app.contract)
             continue;
-        runs.push(await settle(`${name}: the contract`, () => writeApiContract({ ...app.contract, module: app.module, exportName: app.exportName, tsconfig: app.tsconfig, check })));
+        const label = `${name}: the contract`;
+        runs.push(await settle(label, () => writeApiContractInOwnProcess(label, { ...app.contract, module: app.module, exportName: app.exportName, tsconfig: app.tsconfig, check }, contractHeapMegabytes)));
     }
     // Then what is read off the instance itself, which importing the module
-    // builds once for all three.
+    // builds once for all of them.
     for (const [name, app] of apps) {
         const instance = { module: app.module, exportName: app.exportName, check };
         if (app.signatures)
@@ -80,6 +139,8 @@ export const generateApiFiles = async (config, options = {}) => {
         for (const guardFile of app.guardParams ?? []) {
             runs.push(await settle(`${name}: the "${guardFile.guard}" guard parameters`, () => writeApiGuardParams({ ...guardFile, ...instance })));
         }
+        if (app.schemas)
+            runs.push(await settle(`${name}: the schemas`, () => writeApiSchemas({ ...app.schemas, ...instance })));
     }
     return { ok: runs.every((run) => run.ok), lines: runs.flatMap((run) => run.lines) };
 };

package/dist/build/writeApiSchemas.d.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { type LambderModuleLocation } from "./moduleLocation.js";
+import { type LambderNameChanges } from "./generatedTables.js";
+/** The zod schemas of one API, as a source reports them. */
+type LambderApiSchemaPair = {
+    input: z.ZodType;
+    output: z.ZodType;
+};
+/** What writeApiSchemas reads the schemas from: a Lambder instance, or anything else that reports them the same way. */
+export type LambderApiSchemasSource = {
+    /** Every API's input and output schemas by name. Asynchronous, since a Lambder instance loads its lazy groups before it can report every endpoint. */
+    apiSchemaEntries(): Promise<Record<string, LambderApiSchemaPair>> | Record<string, LambderApiSchemaPair>;
+};
+/**
+ * One place where an API's schema does something its written JSON Schema
+ * cannot hold, so the mock does not do it either:
+ *
+ * - `refinement`: a `.refine()`, `.superRefine()` or `.check()` check, or a
+ *   `z.custom()` schema (written as one that takes anything). The mock does
+ *   not run it, so it lets through what the refinement refuses.
+ * - `transform`: a `.transform()` (in the output form written as a schema
+ *   that takes anything), a `z.preprocess()`, a codec, a rewrite such as
+ *   `.trim()` or `.toLowerCase()`, a `z.coerce` schema, a `.catch()`. The mock
+ *   does not apply it: its handler reads the value as posted, and a coerced or
+ *   caught input the server takes, the mock refuses.
+ * - `pipe`: the second schema of a `.pipe()`. The input form carries the
+ *   first, so the mock does not check the second.
+ * - `default`: a default a function computes on each parse, which the file
+ *   cannot hold, so it is left out and the mock fills nothing there.
+ * - `check`: a string check JSON Schema cannot state as zod runs it: a regex
+ *   with flags (`/i`, `/u`), whose pattern means something else without
+ *   them, or a URL's `protocol` or `hostname` rule (`z.httpUrl()` among
+ *   them). The mock does not run it, so it lets through what the check
+ *   refuses.
+ */
+export type LambderApiSchemaLoss = {
+    /** The API whose schema it is. */
+    api: string;
+    /** Which of its schemas: the input a client posts, or the output it receives. */
+    direction: "input" | "output";
+    /** Where, as a JSON pointer into the written schema: `#/properties/name`, or `#` for the whole schema. */
+    path: string;
+    kind: "refinement" | "transform" | "pipe" | "default" | "check";
+};
+export type LambderApiSchemasFileOptions = {
+    /**
+     * The module that exports the instance, usually the server's entry: a
+     * path relative to the working directory, or a file URL. It is imported
+     * in this process, so a TypeScript module needs the process's loader
+     * (`tsx`, `node --import tsx`), as the generator script itself does.
+     */
+    module: LambderModuleLocation;
+    /** The export that holds the instance. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The TypeScript module to write, exporting `apiSchemas`. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk holds what the instance reports now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file and say it is for development only. Default: a note naming writeApiSchemas(). */
+    header?: string;
+    /** End the generated statement with a semicolon. Default: true. The table itself is JSON, double quotes included, whatever the project's style: that is what lets a check read it back. */
+    semicolons?: boolean;
+};
+export type LambderApiSchemasFileResult = {
+    /** False when a check found the file stale or unreadable. Losses do not make it false: they are what the file cannot hold, however current it is. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** True when the file was (re)written; a file that already holds this table is left untouched, however it is formatted. */
+    written: boolean;
+    /** How many APIs the table holds. */
+    count: number;
+    /** Which APIs moved against the file that was on disk. */
+    changes: LambderNameChanges;
+    /** Every place a schema does what its written form cannot hold, sorted by API, direction and place. */
+    losses: LambderApiSchemaLoss[];
+    /** What happened, as lines to print: a summary, one line per API that moved, then one line per loss. */
+    lines: string[];
+};
+/**
+ * Writes every API's input and output schemas as JSON Schema to a module of
+ * plain data, or checks the one on disk, and says which APIs moved and what
+ * their schemas do that the file cannot hold.
+ *
+ * Call it from a generator script beside writeApiOptions, writing to where
+ * the mock's setup reads it:
+ *
+ * ```ts
+ * import { writeApiSchemas } from "lambder/build";
+ *
+ * const result = await writeApiSchemas({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "web/src/mock/apiSchemas.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * The table is compared as the data the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it is neither
+ * stale nor rewritten. The same instance writes the same file on every run.
+ * A module that does not load, an export that is not an instance, or a
+ * schema holding what JSON Schema cannot represent (other than a refinement
+ * or a transform, which are listed) throws.
+ */
+export declare const writeApiSchemas: (options: LambderApiSchemasFileOptions) => Promise<LambderApiSchemasFileResult>;
+export {};

package/dist/build/writeApiSchemas.js

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { z } from "zod";
+import { canonicalJson } from "../shared/util/canonicalJson.js";
+import { LAMBDER_STRIP_UNKNOWN_KEYS } from "../shared/wire/LambderApiSchemaEntries.js";
+import { moduleUrlOf } from "./moduleLocation.js";
+import { headerLinesOf, nameChangesOf, settleGeneratedFile, tableStatementLines } from "./generatedTables.js";
+/*
+ * Every API's input and output schemas as JSON Schema, in a generated module
+ * of plain data a mock validates its calls against: so in development an
+ * endpoint refuses what the server refuses (a length, a format, a range), a
+ * handler reads the payload the server's parse leaves, and an answer goes out
+ * stripped and defaulted as the server sends it.
+ *
+ * The input is written in its input form, what the server's parse takes from
+ * a client. The output is written in its output form, because a mock handler
+ * returns what the client receives (the contract types it so), where a server
+ * handler returns what the schema parses from: the output form is what the
+ * mock has to check and strip.
+ *
+ * z.toJSONSchema writes the schemas, and three things are this writer's own.
+ * A zod object drops the keys it does not declare, which JSON Schema cannot
+ * say, so each such object is marked (LAMBDER_STRIP_UNKNOWN_KEYS) and the mock
+ * drops them again. What zod cannot represent at all (a Date, a bigint, a Map)
+ * throws, naming the API and the place, since a schema the mock reads
+ * differently from the server is the drift this file exists to end. And what
+ * zod represents only in part is listed as a loss, in the result and its
+ * lines: a refinement it leaves out, a transform it does not run, a pipe whose
+ * second schema the input form does not carry, a default a function computes
+ * on each parse, a check it writes without what zod runs it with (a regex's
+ * flags, a URL's protocol rule). Where zod writes a check the mock would read
+ * back as another (a guid as a strict uuid, a custom email pattern as zod's
+ * own), the writer leaves out the misleading part instead.
+ *
+ * The file names every endpoint and every field each takes and gives, so it
+ * is for development alone: imported by the mock's setup, which a production
+ * build never loads.
+ */
+const DEFAULT_HEADER = [
+    "Generated by writeApiSchemas() from lambder/build. Do not edit.",
+    "",
+    "Every API's input schema, in the form a client posts, and output schema,",
+    "in the form a client receives, as JSON Schema (draft 2020-12): what the",
+    "mock validates its calls against, as the server does. Development only:",
+    "it names every endpoint, so only the mock's setup imports it.",
+].join("\n");
+const TABLE_NAME = "apiSchemas";
+/** What each kind of loss says in the lines. */
+const LOSS_WORDING = {
+    refinement: "a refinement, which the mock does not run",
+    transform: "a transform, which the mock does not apply",
+    pipe: "a pipe, whose second schema the mock does not check",
+    default: "a default computed on each parse, which the mock does not fill",
+    check: "a check written without its flags or URL rule, which the mock does not run",
+};
+const defOf = (schema) => schema._zod.def;
+/**
+ * Regex flags that change what a pattern matches. A JSON Schema pattern is
+ * the source alone, so the mock compiles it without them; `g` and `d` change
+ * nothing about a test zod runs from the start of the value.
+ */
+const MEANING_FLAGS = /[imsuvy]/;
+/** zod's own email pattern, which the mock rebuilds a written `format: "email"` with. */
+const DEFAULT_EMAIL_PATTERN = z.email()._zod.def.pattern;
+/** A JSON pointer into the written schema, for a path as z.toJSONSchema reports it. */
+const pointerOf = (path) => ["#", ...path.map((segment) => String(segment).replace(/~/g, "~0").replace(/\//g, "~1"))].join("/");
+/** A value as the JSON it is written as, compared by data: what the file holds of a default. */
+const asWritten = (value) => {
+    const text = JSON.stringify(value);
+    return text === undefined ? undefined : canonicalJson(JSON.parse(text));
+};
+/**
+ * Whether the default zod wrote is computed on each parse: read once more,
+ * it answers otherwise. A default given as a value is copied on each read and
+ * answers the same; one a function computes (an id, a timestamp) would put a
+ * different value in the file on every run, and a value the server never
+ * repeats in every mock call.
+ */
+const computedOnEachParse = (def, written) => {
+    let again;
+    try {
+        again = def.type === "catch" ? def.catchValue?.(undefined) : def.defaultValue;
+    }
+    catch {
+        return true;
+    }
+    return asWritten(again) !== asWritten(written);
+};
+/**
+ * Whether zod cannot represent a schema because of what it does to a value
+ * rather than what it takes: a transform, a z.custom(), a catch whose value is
+ * computed from the failed parse, a coercion (z.coerce.date() parses to a
+ * Date, which JSON Schema has no type for). Each is written as a schema that
+ * takes anything and listed as a loss; anything else zod cannot represent
+ * throws.
+ */
+const isNonCarryable = (def) => def.type === "transform" || def.type === "custom" || def.type === "catch" || def.coerce === true;
+/** One API's schema in the direction given, as plain JSON Schema, with what it does not carry added to `losses`. */
+const jsonSchemaOf = (api, direction, schema, losses) => {
+    if (typeof schema?._zod !== "object") {
+        throw new Error(`writeApiSchemas: API "${api}" reports no zod ${direction} schema.`);
+    }
+    const lose = (path, kind) => {
+        const loss = { api, direction, path: pointerOf(path), kind };
+        if (!losses.some((known) => known.api === loss.api && known.direction === loss.direction && known.path === loss.path && known.kind === loss.kind))
+            losses.push(loss);
+    };
+    const written = z.toJSONSchema(schema, {
+        io: direction,
+        unrepresentable: ({ zodSchema, path, message }) => {
+            const def = defOf(zodSchema);
+            if (!isNonCarryable(def)) {
+                throw new Error(`writeApiSchemas: the ${direction} schema of API "${api}" holds what JSON Schema cannot represent, at ${pointerOf(path)}: ${message}. Declare it as the value it is on the wire (a z.date() as z.iso.datetime(), a bigint as a string).`);
+            }
+            lose(path, def.type === "custom" ? "refinement" : "transform");
+            return "any";
+        },
+        override: ({ zodSchema, jsonSchema, path }) => {
+            const def = defOf(zodSchema);
+            const json = jsonSchema;
+            if (def.type === "object" && def.catchall === undefined) {
+                // zod writes nothing in the input form and false in the
+                // output form, where the parse accepts the key and drops it.
+                delete json.additionalProperties;
+                json[LAMBDER_STRIP_UNKNOWN_KEYS] = true;
+            }
+            for (const check of def.checks ?? []) {
+                if (check._zod.def.check === "custom")
+                    lose(path, "refinement");
+                else if (check._zod.def.check === "overwrite")
+                    lose(path, "transform");
+            }
+            if (def.type === "string") {
+                // The mock rebuilds a written format by its name, with zod's
+                // defaults (a guid as a strict uuid, an email under zod's
+                // own pattern), and the pattern written beside it as given.
+                const formatChecks = [def, ...(def.checks ?? []).map((check) => check._zod.def)].filter((check) => check.check === "string_format");
+                for (const check of formatChecks) {
+                    // The pattern written beside these is the check exactly;
+                    // the format would read back stricter than the server.
+                    if (check.format === "guid" || (check.format === "email" && (check.pattern?.source !== DEFAULT_EMAIL_PATTERN.source || check.pattern.flags !== DEFAULT_EMAIL_PATTERN.flags)))
+                        delete json.format;
+                    if (check.format === "url") {
+                        if (check.protocol || check.hostname)
+                            lose(path, "check");
+                        if (check.normalize)
+                            lose(path, "transform");
+                    }
+                    if (check.pattern && MEANING_FLAGS.test(check.pattern.flags)) {
+                        // Without its flags the pattern refuses what the
+                        // server takes, so it is not written. A format the
+                        // mock rebuilds by name (z.emoji()) still runs it.
+                        const source = check.pattern.source;
+                        if (json.pattern === source)
+                            delete json.pattern;
+                        if (Array.isArray(json.allOf)) {
+                            json.allOf = json.allOf.filter((entry) => entry.pattern !== source);
+                            if (!json.allOf.length)
+                                delete json.allOf;
+                        }
+                        if (check.format === "regex" || !("format" in json))
+                            lose(path, "check");
+                    }
+                }
+                // A string's second pattern goes in allOf, and the mock reads
+                // an allOf entry's pattern only when the entry says string.
+                for (const entry of Array.isArray(json.allOf) ? json.allOf : []) {
+                    if ("pattern" in entry)
+                        entry.type = "string";
+                }
+            }
+            if (def.type === "custom")
+                lose(path, "refinement");
+            if (def.type === "transform")
+                lose(path, "transform");
+            // A coercion, a catch and a pipe change only what an input may
+            // be: a mock handler returns its output already in the form the
+            // client receives, which the output form checks in full.
+            if (direction === "input") {
+                if (def.coerce === true || def.type === "catch")
+                    lose(path, "transform");
+                if (def.type === "pipe") {
+                    const transforms = def.in?._zod.def.type === "transform" || def.out?._zod.def.type === "transform" || def.transform !== undefined;
+                    lose(path, transforms ? "transform" : "pipe");
+                }
+            }
+            if ((def.type === "default" || def.type === "prefault" || def.type === "catch") && "default" in json && computedOnEachParse(def, json.default)) {
+                delete json.default;
+                lose(path, "default");
+            }
+        },
+    });
+    // Through JSON, so what the file holds is exactly the plain data a check
+    // reads back; the draft is the module's, said once in its header.
+    const plain = JSON.parse(JSON.stringify(written));
+    delete plain.$schema;
+    return plain;
+};
+/** Losses in a stable order, so the lines and the result read the same on every run. */
+const compareLosses = (a, b) => a.api.localeCompare(b.api) || a.direction.localeCompare(b.direction) || a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind);
+/** The losses as lines, under one naming how many APIs carry them. */
+const lossLinesOf = (losses) => {
+    if (!losses.length)
+        return [];
+    const apis = new Set(losses.map((loss) => loss.api)).size;
+    return [
+        `  ${apis === 1 ? "1 API carries" : `${apis} APIs carry`} what JSON Schema cannot hold, which the mock does not check:`,
+        ...losses.map((loss) => `  ! ${loss.api} ${loss.direction} ${loss.path}: ${LOSS_WORDING[loss.kind]}`),
+    ];
+};
+/**
+ * The table a generated file holds, read back as data, or null for a file
+ * that does not hold it as written. Read up to the last `as const` in the
+ * file, which is the statement's own: the file holds one statement, and a
+ * schema's description may say "as const" itself.
+ */
+const readSchemaTable = (contents) => {
+    const match = new RegExp(`export const ${TABLE_NAME}\\s*=\\s*([\\s\\S]*)\\s+as const\\b`).exec(contents);
+    if (!match)
+        return null;
+    try {
+        const table = JSON.parse(match[1]);
+        return table !== null && typeof table === "object" && !Array.isArray(table) ? table : null;
+    }
+    catch {
+        return null;
+    }
+};
+const renderSchemasFile = (entries, options) => [
+    ...headerLinesOf(options.header ?? DEFAULT_HEADER),
+    "",
+    ...tableStatementLines({
+        name: TABLE_NAME,
+        doc: "Every API the server registers: its input schema in its input form and its output schema in its output form, as JSON Schema.",
+        value: entries,
+        semicolon: options.semicolons === false ? "" : ";",
+    }),
+    "",
+].join("\n");
+/** Imports the module, finds the instance under its export, and answers the schemas it reports. */
+const loadApiSchemaPairs = async (options) => {
+    const moduleUrl = moduleUrlOf(options.module);
+    const exportName = options.exportName ?? "default";
+    let namespace;
+    try {
+        namespace = await import(moduleUrl);
+    }
+    catch (err) {
+        throw new Error(`writeApiSchemas could not load ${moduleUrl}`, { cause: err });
+    }
+    const source = namespace[exportName];
+    if (typeof source?.apiSchemaEntries !== "function") {
+        throw new Error(`${moduleUrl} has no export "${exportName}" that reports API schemas: name the export holding the instance in exportName`);
+    }
+    return await source.apiSchemaEntries();
+};
+/**
+ * Writes every API's input and output schemas as JSON Schema to a module of
+ * plain data, or checks the one on disk, and says which APIs moved and what
+ * their schemas do that the file cannot hold.
+ *
+ * Call it from a generator script beside writeApiOptions, writing to where
+ * the mock's setup reads it:
+ *
+ * ```ts
+ * import { writeApiSchemas } from "lambder/build";
+ *
+ * const result = await writeApiSchemas({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "web/src/mock/apiSchemas.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * The table is compared as the data the file holds, so a checkout that
+ * rewrote its line endings or a formatter that re-indented it is neither
+ * stale nor rewritten. The same instance writes the same file on every run.
+ * A module that does not load, an export that is not an instance, or a
+ * schema holding what JSON Schema cannot represent (other than a refinement
+ * or a transform, which are listed) throws.
+ */
+export const writeApiSchemas = async (options) => {
+    const file = resolve(options.file);
+    const pairs = await loadApiSchemaPairs(options);
+    const losses = [];
+    const entries = {};
+    for (const api of Object.keys(pairs).sort()) {
+        const pair = pairs[api];
+        entries[api] = { input: jsonSchemaOf(api, "input", pair.input, losses), output: jsonSchemaOf(api, "output", pair.output, losses) };
+    }
+    losses.sort(compareLosses);
+    const previousText = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const previous = previousText === null ? null : readSchemaTable(previousText);
+    const changes = nameChangesOf(entries, previous ?? {});
+    const count = Object.keys(entries).length;
+    const settled = settleGeneratedFile({
+        name: options.file, file, check: options.check, previousText, readBack: previous !== null,
+        tables: [{ name: TABLE_NAME, count, changes }],
+        held: count === 1 ? "1 API" : `${count} APIs`,
+        tablesNoun: "the schema table",
+        unmovedLine: "no schemas changed",
+        render: () => renderSchemasFile(entries, options),
+    });
+    return { ...settled, lines: [...settled.lines, ...lossLinesOf(losses)], file, count, changes, losses };
+};

package/dist/build.d.ts

@@ -19,8 +19,10 @@ export type { LambderApiOptionsFileOptions, LambderApiOptionsFileResult, } from
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
 export type { LambderApiGuardParamsFileOptions, LambderApiGuardParamsFileResult, } from "./build/writeApiGuardParams.js";
 export type { LambderApiOptionsSource, LambderNameChanges } from "./build/generatedTables.js";
+export { writeApiSchemas } from "./build/writeApiSchemas.js";
+export type { LambderApiSchemasSource, LambderApiSchemasFileOptions, LambderApiSchemasFileResult, LambderApiSchemaLoss, } from "./build/writeApiSchemas.js";
 export { checkApiRefusals } from "./build/checkApiRefusals.js";
 export type { LambderApiRefusalCheckOptions, LambderApiRefusalCheckResult, LambderRefusalCheckFinding, } from "./build/checkApiRefusals.js";
 export { generateApiFiles } from "./build/generateApiFiles.js";
-export type { LambderApiFilesConfig, LambderApiFilesApp, LambderApiFilesResult } from "./build/generateApiFiles.js";
+export type { LambderApiFilesConfig, LambderApiFilesApp, LambderApiFilesOptions, LambderApiFilesResult } from "./build/generateApiFiles.js";
 export type { LambderModuleLocation } from "./build/moduleLocation.js";

package/dist/build.js

@@ -14,5 +14,7 @@ export { writeApiSignatures } from "./build/writeApiSignatures.js";
 export { writeApiContract } from "./build/writeApiContract.js";
 export { writeApiOptions } from "./build/writeApiOptions.js";
 export { writeApiGuardParams } from "./build/writeApiGuardParams.js";
+// Development only: the schemas a mock validates its calls against.
+export { writeApiSchemas } from "./build/writeApiSchemas.js";
 export { checkApiRefusals } from "./build/checkApiRefusals.js";
 export { generateApiFiles } from "./build/generateApiFiles.js";