lambder 8.0.2 → 8.1.1

package/dist/build/moduleLocation.js

@@ -0,0 +1,6 @@
+import { resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+/** The module as a file URL. A string that already is one is taken as one: resolved as a path, it would name a directory called "file:". */
+export const moduleUrlOf = (module) => typeof module === "string" && !/^file:/i.test(module) ? pathToFileURL(resolve(module)).href : new URL(module).href;
+/** The module as a path on disk. */
+export const modulePathOf = (module) => fileURLToPath(moduleUrlOf(module));

package/dist/build/writeApiContract.d.ts

@@ -0,0 +1,78 @@
+import { type LambderModuleLocation } from "./moduleLocation.js";
+export type LambderApiContractFileOptions = {
+    /** The module that exports the Lambder instance, usually the server's entry: a path relative to the working directory, or a file URL. */
+    module: LambderModuleLocation;
+    /** The export that holds the instance, whose ApiContract is written out. Default: "default", the module's default export. */
+    exportName?: string;
+    /** The name the written module exports the contract type under. Default: "ApiContractType". */
+    typeName?: string;
+    /** The tsconfig.json the module compiles under, whose compiler options and path aliases resolve its imports. Relative to the working directory. Default: the nearest tsconfig.json at or above the module's directory. */
+    tsconfig?: string;
+    /** The TypeScript module to write. Relative to the working directory. */
+    file: string;
+    /** Write nothing, and answer whether the file on disk is what the contract prints now. Default: false. */
+    check?: boolean;
+    /** The comment the file opens with, one `//` line per line. It should name what generates the file. Default: a note naming writeApiContract(). */
+    header?: string;
+    /** Quotes in the generated module. Default: "double". */
+    quotes?: "single" | "double";
+    /** End the generated declarations and members with semicolons. Default: true. */
+    semicolons?: boolean;
+};
+export type LambderApiContractFileResult = {
+    /** False when the contract could not be read or printed, a check found the file stale, or the printed type was not the contract's. */
+    ok: boolean;
+    /** The absolute path. */
+    file: string;
+    /** How many APIs the contract holds (0 when it could not be read). */
+    count: number;
+    /** True when the file was (re)written; a file that already holds this text is left untouched. */
+    written: boolean;
+    /** APIs whose printed types differ from the file that was on disk, by name, counting the declarations each refers to. */
+    changed: string[];
+    added: string[];
+    removed: string[];
+    /** What happened, as lines to print: a summary, then one line per API that moved or per member that could not be printed. */
+    lines: string[];
+};
+/**
+ * Writes an app's API contract type to a TypeScript module as plain types,
+ * or checks the one on disk, and names the APIs whose types moved.
+ *
+ * The contract is the ApiContract property of the instance the module
+ * exports, read through the TypeScript compiler under the server's own
+ * tsconfig; nothing of the server runs. Every type in it is printed as the
+ * structure it resolves to: zod's inferences, mapped and conditional types and
+ * the server's own types become plain object types, unions and literals. The
+ * written module imports nothing, not even lambder, and exports one type
+ * alias, `typeName`. Only the default library's interfaces (Date) are printed
+ * by name. A non-generic named type is printed once, as a declaration of its
+ * own that the entries refer to.
+ *
+ * Anything with no plain form fails the call and names where it sits: a
+ * function, a symbol-keyed property, an enum, a class's private member, or a
+ * type parameter the contract leaves open. Property `readonly` modifiers are
+ * not carried over (they never decide assignability); readonly arrays and
+ * tuples are.
+ *
+ * ```ts
+ * import { writeApiContract } from "lambder/build";
+ *
+ * const result = await writeApiContract({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiContract.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * A check compares the text, so the file should be left out of formatters;
+ * each declaration carries a `// prettier-ignore` line for Prettier. A write
+ * that changes the file first compiles the new text beside the server's
+ * sources and checks every entry against the contract both ways, and writes
+ * nothing when one differs. The file is written to a temporary file renamed
+ * over the old one, so a build reading it meanwhile never sees half of it.
+ */
+export declare const writeApiContract: (options: LambderApiContractFileOptions) => Promise<LambderApiContractFileResult>;

package/dist/build/writeApiContract.js

@@ -0,0 +1,302 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { ContractTypePrinter } from "./ContractTypePrinter.js";
+import { modulePathOf } from "./moduleLocation.js";
+import { writeFileAtomically } from "./writeFileAtomically.js";
+const DEFAULT_HEADER = [
+    "Generated by writeApiContract() from lambder/build. Do not edit.",
+    "",
+    "The server's API contract written out as plain types, so a client compiles",
+    "the contract without compiling the server's schemas and code.",
+].join("\n");
+const INDENT = "    ";
+/** How many compiler diagnostics a failure prints before it stops. */
+const DIAGNOSTIC_LIMIT = 20;
+/**
+ * Writes an app's API contract type to a TypeScript module as plain types,
+ * or checks the one on disk, and names the APIs whose types moved.
+ *
+ * The contract is the ApiContract property of the instance the module
+ * exports, read through the TypeScript compiler under the server's own
+ * tsconfig; nothing of the server runs. Every type in it is printed as the
+ * structure it resolves to: zod's inferences, mapped and conditional types and
+ * the server's own types become plain object types, unions and literals. The
+ * written module imports nothing, not even lambder, and exports one type
+ * alias, `typeName`. Only the default library's interfaces (Date) are printed
+ * by name. A non-generic named type is printed once, as a declaration of its
+ * own that the entries refer to.
+ *
+ * Anything with no plain form fails the call and names where it sits: a
+ * function, a symbol-keyed property, an enum, a class's private member, or a
+ * type parameter the contract leaves open. Property `readonly` modifiers are
+ * not carried over (they never decide assignability); readonly arrays and
+ * tuples are.
+ *
+ * ```ts
+ * import { writeApiContract } from "lambder/build";
+ *
+ * const result = await writeApiContract({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiContract.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
+ * console.log(result.lines.join("\n"));
+ * process.exit(result.ok ? 0 : 1);
+ * ```
+ *
+ * A check compares the text, so the file should be left out of formatters;
+ * each declaration carries a `// prettier-ignore` line for Prettier. A write
+ * that changes the file first compiles the new text beside the server's
+ * sources and checks every entry against the contract both ways, and writes
+ * nothing when one differs. The file is written to a temporary file renamed
+ * over the old one, so a build reading it meanwhile never sees half of it.
+ */
+export const writeApiContract = async (options) => {
+    const ts = await loadTypeScript();
+    const file = resolve(options.file);
+    const modulePath = modulePathOf(options.module);
+    const exportName = options.exportName ?? "default";
+    const typeName = options.typeName ?? "ApiContractType";
+    const style = { quote: options.quotes === "single" ? "'" : "\"", semicolon: options.semicolons === false ? "" : ";" };
+    let count = 0;
+    const result = (ok, written, lines, moved) => ({ ok, file, count, written, changed: moved?.changed ?? [], added: moved?.added ?? [], removed: moved?.removed ?? [], lines });
+    const project = readProject(ts, options.tsconfig, modulePath);
+    if ("failure" in project)
+        return result(false, false, [`✗ ${options.module}: ${project.failure}`, ...(project.details ?? [])]);
+    // The program is used for the printing alone, and dropped before the
+    // verification builds its own: only the parsed files carry over.
+    const printing = printContractFile(ts, project, modulePath, exportName, typeName, style, options.header);
+    if ("failure" in printing)
+        return result(false, false, [`✗ ${options.module}: ${printing.failure}`, ...(printing.details ?? [])]);
+    count = printing.count;
+    const { text, parsedFiles } = printing;
+    const previous = existsSync(file) ? readFileSync(file, "utf8") : null;
+    const moved = describeContractChanges(ts, typeName, previous, text);
+    const unchanged = previous !== null && previous.replace(/\r\n/g, "\n") === text;
+    const movedSummary = moved.lines.length ? [`  ${moved.summary}`, ...moved.lines] : [];
+    if (options.check) {
+        if (unchanged)
+            return result(true, false, [`✓ ${options.file} matches the ${count} APIs of ${typeName}`], moved);
+        return result(false, false, [`✗ ${options.file} is stale: regenerate it`, ...(movedSummary.length ? movedSummary : ["  no API's types changed; the header or layout did"])], moved);
+    }
+    if (unchanged)
+        return result(true, false, [`✓ ${options.file} is up to date (${count} APIs)`], moved);
+    const mismatches = verifyPrintedContract(ts, project, parsedFiles, { modulePath, exportName }, { file, text, typeName });
+    if (mismatches.length)
+        return result(false, false, [`✗ the printed ${typeName} is not the contract of ${exportName} in ${options.module}, so ${options.file} was not written:`, ...mismatches.map((line) => `  ${line}`)], moved);
+    writeFileAtomically(file, text, previous !== null);
+    return result(true, true, [`✓ Wrote ${options.file} (${count} APIs)`, ...(movedSummary.length ? movedSummary : ["  no API's types changed; the header or layout did"])], moved);
+};
+/** The compiler API writeApiContract reads with. TypeScript 7 ships none, so its package answers the import without one. */
+const loadTypeScript = async () => {
+    const requirement = "writeApiContract reads the contract through the TypeScript compiler API (typescript 5.4 to 6.x): install one beside lambder, such as in the generator's own package when the app is on TypeScript 7";
+    let ts;
+    try {
+        ts = (await import("typescript")).default;
+    }
+    catch (err) {
+        throw new Error(requirement, { cause: err });
+    }
+    if (typeof ts?.createProgram !== "function")
+        throw new Error(`${requirement}; the typescript installed (${ts?.version ?? "unknown"}) has no compiler API`);
+    return ts;
+};
+/** The server's compiler options, and the root files a program over the module needs: the module, and the project's own declaration files, which may declare globals the module relies on. */
+const readProject = (ts, tsconfig, modulePath) => {
+    const configPath = tsconfig ? resolve(tsconfig) : ts.findConfigFile(dirname(modulePath), ts.sys.fileExists);
+    if (!configPath)
+        return { failure: "no tsconfig.json in its directory or above it; name the server's in tsconfig" };
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error)
+        return { failure: `${configPath} could not be read`, details: formatDiagnostics(ts, [read.error]) };
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath), undefined, configPath);
+    if (parsed.errors.length)
+        return { failure: `${configPath} has errors`, details: formatDiagnostics(ts, parsed.errors) };
+    return {
+        // Nothing is emitted, and a composite project's rule that every file be
+        // listed in it does not hold for a program rooted at one module.
+        options: { ...parsed.options, noEmit: true, composite: false, incremental: false, declaration: false },
+        rootNames: [modulePath, ...parsed.fileNames.filter((fileName) => fileName.endsWith(".d.ts"))],
+    };
+};
+/** An export of a module, followed through a re-export or an `export default` of a name. */
+const readExport = (ts, program, checker, modulePath, exportName) => {
+    const sourceFile = program.getSourceFile(modulePath);
+    if (!sourceFile)
+        return { failure: "the module was not found" };
+    const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
+    const exported = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === exportName);
+    if (!exported)
+        return { failure: `the module has no export named "${exportName}"` };
+    return exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+};
+/** The ApiContract of the instance a module exports, from a module that compiles. */
+const readInstanceContract = (ts, program, checker, modulePath, exportName) => {
+    const sourceFile = program.getSourceFile(modulePath);
+    if (!sourceFile)
+        return { failure: "the module was not found" };
+    // A module with errors can infer `any` where the contract meant a type,
+    // and `any` prints and verifies as itself.
+    const diagnostics = [...program.getSyntacticDiagnostics(sourceFile), ...program.getSemanticDiagnostics(sourceFile)];
+    if (diagnostics.length)
+        return { failure: "the module does not compile", details: formatDiagnostics(ts, diagnostics) };
+    const instance = readExport(ts, program, checker, modulePath, exportName);
+    if ("failure" in instance)
+        return { failure: `${instance.failure}; name the export that holds the Lambder instance in exportName` };
+    const contract = checker.getPropertyOfType(checker.getTypeOfSymbol(instance), "ApiContract");
+    if (!contract)
+        return { failure: `"${exportName}" is not a Lambder instance: it has no ApiContract` };
+    return checker.getTypeOfSymbol(contract);
+};
+/** The contract type a printed module exports. */
+const readPrintedContract = (ts, program, checker, file, typeName) => {
+    const exported = readExport(ts, program, checker, file, typeName);
+    if ("failure" in exported)
+        return exported;
+    if (!(exported.flags & ts.SymbolFlags.Type))
+        return { failure: `${typeName} is not a type` };
+    return checker.getDeclaredTypeOfSymbol(exported);
+};
+const printContractFile = (ts, project, modulePath, exportName, typeName, style, header) => {
+    const program = ts.createProgram({ rootNames: project.rootNames, options: project.options });
+    const checker = program.getTypeChecker();
+    const contract = readInstanceContract(ts, program, checker, modulePath, exportName);
+    if ("failure" in contract)
+        return contract;
+    const printer = new ContractTypePrinter(ts, program, checker, style, typeName);
+    const printed = printer.printContract(contract);
+    if (printed.failures.length) {
+        return { failure: `${typeName} holds types with no plain form, which only the server's sources could name:`, details: printed.failures.map((line) => `  ${line}`) };
+    }
+    return {
+        text: renderContractFile(printer, printed, typeName, style, header),
+        count: printed.entries.length,
+        parsedFiles: new Map(program.getSourceFiles().map((sourceFile) => [sourceFile.fileName, sourceFile])),
+    };
+};
+const renderContractFile = (printer, printed, typeName, style, header = DEFAULT_HEADER) => {
+    const indented = (text) => INDENT + text.replace(/\n/g, `\n${INDENT}`);
+    const entries = printed.entries.map(({ name, text }) => indented(printer.labeledValue(`${printer.keyOf(name)}:`, text)) + style.semicolon);
+    return [
+        ...header.split("\n").map((line) => line ? `// ${line}` : "//"),
+        "",
+        // Kept as written by a formatter that honours it: a check compares
+        // the text.
+        "// prettier-ignore",
+        entries.length ? [`export type ${typeName} = {`, ...entries, `}${style.semicolon}`].join("\n") : `export type ${typeName} = {}${style.semicolon}`,
+        ...printed.declarations.flatMap(({ name, text }) => ["", "// prettier-ignore", printer.labeledValue(`type ${name} =`, text) + style.semicolon]),
+        "",
+    ].join("\n");
+};
+/**
+ * Compiles the printed text beside the server's sources, from the files the
+ * printing parsed, and checks each entry against the contract's in both
+ * directions. Answers the entries that differ, or the diagnostics of a text
+ * that does not compile; nothing when the two are the same type.
+ */
+const verifyPrintedContract = (ts, project, parsedFiles, { modulePath, exportName }, { file, text, typeName }) => {
+    const canonical = (fileName) => {
+        const slashed = fileName.replace(/\\/g, "/");
+        return ts.sys.useCaseSensitiveFileNames ? slashed : slashed.toLowerCase();
+    };
+    const printedFile = canonical(file);
+    const isPrinted = (fileName) => canonical(fileName) === printedFile;
+    const host = ts.createCompilerHost(project.options, true);
+    const { getSourceFile, fileExists, readFile } = host;
+    host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => isPrinted(fileName)
+        ? ts.createSourceFile(fileName, text, languageVersion, true)
+        : parsedFiles.get(fileName) ?? getSourceFile.call(host, fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    host.fileExists = (fileName) => isPrinted(fileName) || fileExists.call(host, fileName);
+    host.readFile = (fileName) => isPrinted(fileName) ? text : readFile.call(host, fileName);
+    const program = ts.createProgram({ rootNames: [...project.rootNames, file], options: project.options, host });
+    const printedSource = program.getSourceFile(file);
+    const diagnostics = [...program.getSyntacticDiagnostics(printedSource), ...program.getSemanticDiagnostics(printedSource)];
+    if (diagnostics.length)
+        return ["the printed text does not compile:", ...formatDiagnostics(ts, diagnostics)];
+    const checker = program.getTypeChecker();
+    const contract = readInstanceContract(ts, program, checker, modulePath, exportName);
+    const reprinted = readPrintedContract(ts, program, checker, file, typeName);
+    if ("failure" in contract)
+        return [contract.failure];
+    if ("failure" in reprinted)
+        return [`the printed text: ${reprinted.failure}`];
+    const mismatches = [];
+    for (const entry of checker.getPropertiesOfType(contract)) {
+        const counterpart = checker.getPropertyOfType(reprinted, entry.name);
+        if (!counterpart) {
+            mismatches.push(`${entry.name}: missing from the printed type`);
+            continue;
+        }
+        const original = checker.getTypeOfSymbol(entry);
+        const copy = checker.getTypeOfSymbol(counterpart);
+        if (!checker.isTypeAssignableTo(original, copy))
+            mismatches.push(`${entry.name}: the contract's type is not assignable to the printed one`);
+        if (!checker.isTypeAssignableTo(copy, original))
+            mismatches.push(`${entry.name}: the printed type is not assignable to the contract's`);
+    }
+    for (const entry of checker.getPropertiesOfType(reprinted)) {
+        if (!checker.getPropertyOfType(contract, entry.name))
+            mismatches.push(`${entry.name}: in the printed type, not in the contract`);
+    }
+    return mismatches;
+};
+/**
+ * Which entries a file's text and the new text print differently, counting
+ * the declarations each entry refers to, directly or through another one: a
+ * change to a shared named type moves every entry that uses it.
+ */
+const describeContractChanges = (ts, typeName, previous, text) => {
+    const before = previous === null ? new Map() : entryClosures(ts, typeName, previous);
+    const after = entryClosures(ts, typeName, text);
+    const changed = [...after.keys()].filter((name) => before.has(name) && before.get(name) !== after.get(name));
+    const added = [...after.keys()].filter((name) => !before.has(name));
+    const removed = [...before.keys()].filter((name) => !after.has(name));
+    return {
+        changed, added, removed,
+        lines: [...changed.map((name) => `  ~ ${name}`), ...added.map((name) => `  + ${name}`), ...removed.map((name) => `  - ${name}`)],
+        summary: `${changed.length} changed, ${added.length} added, ${removed.length} removed (${after.size - changed.length - added.length} unchanged)`,
+    };
+};
+/** Each entry of the contract type in a printed module, as its own text followed by every declaration it reaches. Empty when the text holds no such type. */
+const entryClosures = (ts, typeName, text) => {
+    const sourceFile = ts.createSourceFile("contract.ts", text, ts.ScriptTarget.Latest, true);
+    const declared = new Map();
+    let contract;
+    for (const statement of sourceFile.statements) {
+        if (!ts.isTypeAliasDeclaration(statement))
+            continue;
+        if (statement.name.text === typeName && ts.isTypeLiteralNode(statement.type))
+            contract = statement.type;
+        else
+            declared.set(statement.name.text, statement.type);
+    }
+    const closures = new Map();
+    for (const member of contract?.members ?? []) {
+        if (!ts.isPropertySignature(member) || !member.type || !(ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)))
+            continue;
+        const reached = new Set();
+        const visit = (node) => {
+            if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+                const name = node.typeName.text;
+                const body = declared.get(name);
+                if (body && !reached.has(name)) {
+                    reached.add(name);
+                    visit(body);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(member.type);
+        closures.set(member.name.text, [member.type.getText(sourceFile), ...[...reached].sort().map((name) => `type ${name} = ${declared.get(name).getText(sourceFile)}`)].join("\n"));
+    }
+    return closures;
+};
+const formatDiagnostics = (ts, diagnostics) => {
+    const shown = ts.formatDiagnostics(diagnostics.slice(0, DIAGNOSTIC_LIMIT), {
+        getCanonicalFileName: (fileName) => fileName,
+        getCurrentDirectory: () => process.cwd(),
+        getNewLine: () => "\n",
+    }).trim().split("\n").map((line) => `  ${line}`);
+    return diagnostics.length > DIAGNOSTIC_LIMIT ? [...shown, `  ... and ${diagnostics.length - DIAGNOSTIC_LIMIT} more`] : shown;
+};

package/dist/build/writeApiSignatures.d.ts

@@ -1,4 +1,5 @@
 import type { LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
+import { type LambderModuleLocation } from "./moduleLocation.js";
 /**
  * How the fresh process reports its comparison: one line on stdout starting
  * with this, then the verdict as JSON. The line, not the exit status, is the
@@ -13,6 +14,15 @@ export type LambderApiSignatureSource = {
     apiSignatureEntries(): Promise<LambderApiSignatureEntry[]>;
 };
 export type LambderApiSignatureFileOptions = {
+    /**
+     * 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 `apiSignatures`. Relative to the working directory. */
     file: string;
     /** Write nothing, and answer whether the file on disk is what the registrations produce now. Default: false. */
@@ -25,30 +35,19 @@ export type LambderApiSignatureFileOptions = {
     semicolons?: boolean;
     /**
      * After writing, or after a check that found the file current, load the
-     * module that holds the instance in a fresh Node process and check the
-     * file against what it digests there. A schema built from the clock or a
-     * random source digests differently in every process; this catches it by
-     * endpoint name instead of letting signatures change on every build. Only
-     * that module is loaded, never the calling script, so nothing the script
-     * does runs twice; the module's own top-level code does run again. The
-     * fresh process gets this process's Node flags (`--import`, `--require`,
+     * module again in a fresh Node process and check the file against what
+     * it digests there. A schema built from the clock or a random source
+     * digests differently in every process; this catches it by endpoint name
+     * instead of letting signatures change on every build. Only the module is
+     * loaded there, never the calling script, so nothing the script does runs
+     * twice; the module's own top-level code does run again. The fresh
+     * process gets this process's Node flags (`--import`, `--require`,
      * `--loader`, `--conditions`) less the inspector, watch mode, the test
      * runner and the eval flags (`-e`, `-p`, `--input-type`), so a TypeScript
      * module loads there as it did here when its loader is on the command
-     * line or in NODE_OPTIONS. Default: not verified.
+     * line or in NODE_OPTIONS. Default: true.
      */
-    verifyInFreshProcess?: {
-        /**
-         * The module that exports the instance: a path relative to the
-         * working directory, or a file URL, as a URL such as
-         * `new URL("../backend/index.js", import.meta.url)` beside the
-         * generator's own import of it, or as the string
-         * `import.meta.resolve()` answers.
-         */
-        module: string | URL;
-        /** The export that holds the instance. Default: "default", the module's default export. */
-        exportName?: string;
-    };
+    verifyInFreshProcess?: boolean;
 };
 export type LambderApiSignatureFileResult = {
     /** False when a check found the file stale, or a fresh process digested different signatures or never compared them. */
@@ -89,21 +88,27 @@ export declare const describeSignatureChanges: (entries: LambderApiSignatureEntr
  * that endpoint, so this is the line that says how wide a deploy's reload
  * will be.
  *
- * Call it from a generator script that imports the app's instance:
+ * Call it from a generator script, naming the module that exports the app's
+ * instance, as writeApiContract takes it:
  *
  * ```ts
  * import { writeApiSignatures } from "lambder/build";
- * import { lambder } from "../server/src/index.js";
  *
- * const result = await writeApiSignatures(lambder, { file: "shared/generated/apiSignatures.generated.ts", check: process.argv.includes("--check") });
+ * const result = await writeApiSignatures({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiSignatures.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
  * console.log(result.lines.join("\n"));
  * process.exit(result.ok ? 0 : 1);
  * ```
  *
  * Signatures are compared as the map the file holds, so a checkout that
  * rewrote its line endings or a formatter that re-indented it or unquoted
- * its keys is neither stale nor rewritten. `verifyInFreshProcess` also
- * checks the file, written or found current, against the instance's module
- * loaded in a fresh process.
+ * its keys is neither stale nor rewritten. The file, written or found
+ * current, is then checked again against the module loaded in a fresh
+ * process (see `verifyInFreshProcess`). A module that does not load, or an
+ * export that is not an instance, throws.
  */
-export declare const writeApiSignatures: (source: LambderApiSignatureSource, options: LambderApiSignatureFileOptions) => Promise<LambderApiSignatureFileResult>;
+export declare const writeApiSignatures: (options: LambderApiSignatureFileOptions) => Promise<LambderApiSignatureFileResult>;

package/dist/build/writeApiSignatures.js

@@ -1,7 +1,9 @@
 import { spawnSync } from "child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "fs";
-import { dirname, resolve } from "path";
-import { fileURLToPath, pathToFileURL } from "url";
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+import { moduleUrlOf } from "./moduleLocation.js";
+import { writeFileAtomically } from "./writeFileAtomically.js";
 /*
  * The signature file every app with apiSignatures needs, written and checked
  * by the framework that defines it.
@@ -116,25 +118,44 @@ const renderSignatureFile = (entries, options) => {
  * that endpoint, so this is the line that says how wide a deploy's reload
  * will be.
  *
- * Call it from a generator script that imports the app's instance:
+ * Call it from a generator script, naming the module that exports the app's
+ * instance, as writeApiContract takes it:
  *
  * ```ts
  * import { writeApiSignatures } from "lambder/build";
- * import { lambder } from "../server/src/index.js";
  *
- * const result = await writeApiSignatures(lambder, { file: "shared/generated/apiSignatures.generated.ts", check: process.argv.includes("--check") });
+ * const result = await writeApiSignatures({
+ *     module: "server/src/index.ts",   // export const lambder = initLambder()...
+ *     exportName: "lambder",
+ *     file: "shared/generated/apiSignatures.generated.ts",
+ *     check: process.argv.includes("--check"),
+ * });
  * console.log(result.lines.join("\n"));
  * process.exit(result.ok ? 0 : 1);
  * ```
  *
  * Signatures are compared as the map the file holds, so a checkout that
  * rewrote its line endings or a formatter that re-indented it or unquoted
- * its keys is neither stale nor rewritten. `verifyInFreshProcess` also
- * checks the file, written or found current, against the instance's module
- * loaded in a fresh process.
+ * its keys is neither stale nor rewritten. The file, written or found
+ * current, is then checked again against the module loaded in a fresh
+ * process (see `verifyInFreshProcess`). A module that does not load, or an
+ * export that is not an instance, throws.
  */
-export const writeApiSignatures = async (source, options) => {
+export const writeApiSignatures = async (options) => {
     const file = resolve(options.file);
+    const moduleUrl = moduleUrlOf(options.module);
+    const exportName = options.exportName ?? "default";
+    let namespace;
+    try {
+        namespace = await import(moduleUrl);
+    }
+    catch (err) {
+        throw new Error(`writeApiSignatures could not load ${moduleUrl}`, { cause: err });
+    }
+    const source = namespace[exportName];
+    if (typeof source?.apiSignatureEntries !== "function") {
+        throw new Error(`${moduleUrl} has no export "${exportName}" that lists API signatures: name the export holding the instance in exportName`);
+    }
     const entries = await source.apiSignatureEntries();
     const previous = existsSync(file) ? readFileSync(file, "utf8") : null;
     const { changed, added, removedKeys, movedLines, summary } = describeSignatureChanges(entries, previous === null ? {} : readSignatureMap(previous));
@@ -142,7 +163,7 @@ export const writeApiSignatures = async (source, options) => {
     const result = (ok, written, lines) => ({ ok, file, count: entries.length, written, changed, added, removedKeys, lines });
     // A stale file is the answer by itself: a fresh process could only find
     // it stale again. A current one goes on to the verification, as a write
-    // does, so a check that names verifyInFreshProcess verifies.
+    // does.
     let written = false;
     let lines;
     if (options.check) {
@@ -155,44 +176,18 @@ export const writeApiSignatures = async (source, options) => {
         // formatted, so a watcher or an incremental build sees no change
         // where there is none, and a formatter's or a checkout's version of
         // the file is not rewritten back on every run. A change of header,
-        // quotes or semicolons shows the next time the map changes. The write
-        // goes to a file beside the target and is renamed over it, so a build
-        // reading the file meanwhile sees the old map or the new one, never
-        // half of one. A symlink is followed to the file it names: renamed
-        // over, the link itself would become the new file and its target
-        // would keep the old map.
+        // quotes or semicolons shows the next time the map changes.
         written = !unchanged;
-        if (written) {
-            const target = previous === null ? file : realpathSync(file);
-            mkdirSync(dirname(target), { recursive: true });
-            const partial = `${target}.${process.pid}.tmp`;
-            try {
-                writeFileSync(partial, renderSignatureFile(entries, options));
-                renameSync(partial, target);
-            }
-            catch (err) {
-                rmSync(partial, { force: true });
-                throw err;
-            }
-        }
+        if (written)
+            writeFileAtomically(file, renderSignatureFile(entries, options), previous !== null);
         lines = [
             written ? `✓ Wrote ${options.file} (${entries.length} APIs)` : `✓ ${options.file} is up to date (${entries.length} APIs)`,
             ...(movedLines.length ? [`  ${summary}`, ...movedLines] : ["  no signatures changed: this build forces no reloads"]),
         ];
     }
-    if (!options.verifyInFreshProcess)
+    if (options.verifyInFreshProcess === false)
         return result(true, written, lines);
-    const { module: instanceModule, exportName = "default" } = options.verifyInFreshProcess;
-    const request = {
-        // A string that is already a file URL (what import.meta.resolve()
-        // answers) is taken as one: resolved as a path, it would name a
-        // directory called "file:" under the working directory.
-        moduleUrl: typeof instanceModule === "string" && !/^file:/i.test(instanceModule)
-            ? pathToFileURL(resolve(instanceModule)).href
-            : new URL(instanceModule).href,
-        exportName,
-        file,
-    };
+    const request = { moduleUrl, exportName, file };
     const child = spawnSync(process.execPath, [...freshProcessNodeFlags(process.execArgv), fileURLToPath(FRESH_PROCESS_ENTRY), JSON.stringify(request)], {
         encoding: "utf8",
         timeout: VERIFY_TIMEOUT_MS,

package/dist/build/writeFileAtomically.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes a generated file so that a build reading it meanwhile sees the old
+ * contents or the new, never half of either: the text goes to a file beside
+ * the target and is renamed over it. A symlink is followed to the file it
+ * names, since renamed over, the link itself would become the new file and
+ * its target would keep the old contents.
+ */
+export declare const writeFileAtomically: (file: string, contents: string, exists: boolean) => void;

package/dist/build/writeFileAtomically.js

@@ -0,0 +1,22 @@
+import { mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "fs";
+import { dirname } from "path";
+/**
+ * Writes a generated file so that a build reading it meanwhile sees the old
+ * contents or the new, never half of either: the text goes to a file beside
+ * the target and is renamed over it. A symlink is followed to the file it
+ * names, since renamed over, the link itself would become the new file and
+ * its target would keep the old contents.
+ */
+export const writeFileAtomically = (file, contents, exists) => {
+    const target = exists ? realpathSync(file) : file;
+    mkdirSync(dirname(target), { recursive: true });
+    const partial = `${target}.${process.pid}.tmp`;
+    try {
+        writeFileSync(partial, contents);
+        renameSync(partial, target);
+    }
+    catch (err) {
+        rmSync(partial, { force: true });
+        throw err;
+    }
+};