lambder 8.0.2 → 8.1.1

package/CHANGELOG.md

@@ -9,7 +9,121 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
-## [8.0.1] - 2026-09-25
+## [8.1.1] - 2026-09-26
+
+Two additions, and three breaking changes a minor line carries here on
+purpose. An app's contract can now be written out as a generated file of
+plain types for its clients to import, which does by default what
+`LambderFlattenContract` asked each app to spell out, so that helper is gone.
+And direct uploads, files posted from the browser straight to S3 on tickets
+the server signs, are part of the framework.
+
+### Added
+
+- **`writeApiContract` in `lambder/build`: the contract as a generated file.**
+  A client that imports `typeof lambder.ApiContract` from the server compiles
+  the server to get it, every endpoint's schemas and the libraries they infer
+  through included, and reads it as the intersection chaining built. In a
+  193-endpoint app that was 17 of the frontend check's 19 million type
+  instantiations and 2.4 of its 4.8 GB. `writeApiContract` reads the
+  `ApiContract` of the instance a module exports (`module`, `exportName`)
+  through the TypeScript compiler, under the server's own tsconfig and
+  without running any of it, and writes the contract as one object type with
+  plain members to a module that imports nothing. The app declares nothing
+  for it, and its clients (a frontend, another service's
+  `LambderInvokeCaller`, its own tests through `lambderTestApp`) import the
+  type from there: the same frontend check fell to 1.8 million
+  instantiations and 2.4 GB.
+  - Every type is printed as the structure it resolves to. The default
+    library's interfaces (`Date`) keep their names, a non-generic named type
+    (an alias, an interface, a class) is printed once as a declaration the
+    entries refer to, which is also how a recursive type refers to itself,
+    and properties keep the order they are written in, so the file changes
+    only when an API does.
+  - Anything with no plain form fails the call and names where it sits: a
+    function, a symbol key, an enum, a class's private member, an open type
+    parameter, and a type a compile error left unresolved, wherever in the
+    server's sources the error is.
+  - A write compiles the new text beside the server's sources and checks each
+    entry against the contract in both directions before it touches the file.
+    `check: true` writes nothing and fails a stale file. Both name the APIs
+    that moved, counting a change to a shared declaration against every API
+    that reaches it.
+  - `typescript` 5.4 or later is an optional peer dependency, loaded only when
+    `writeApiContract` runs. It needs the compiler API, so 5.x or 6.x:
+    TypeScript 7 ships none, and the call says so when it finds a 7.
+
+  See [the contract as a generated file](./docs/apis.md#the-contract-as-a-generated-file).
+
+- **Direct uploads.** A file too large for an API payload goes from the
+  browser straight to object storage, on a ticket the app's endpoint signs
+  for exactly that file: its key, byte size, content type and SHA-256, all
+  enforced by storage, and verified by the server before the app's record
+  counts it as uploaded.
+  - `LambderUploadBucket`, the interface a bucket implements: sign a ticket,
+    verify what arrived, sign a download link, and read, write, copy and
+    delete objects for the rest of their life. `LambderS3UploadBucket`
+    implements it over an S3 presigned POST whose policy pins every fact;
+    `@aws-sdk/s3-presigned-post` and `@aws-sdk/s3-request-presigner` join
+    `@aws-sdk/client-s3` as optional peers, each loaded on first use.
+    `writeObject` sends the checksum it is given or has the SDK compute one.
+  - Lifetimes at both levels: `ticketLifetimeSeconds` and
+    `downloadLifetimeSeconds` on the bucket, `lifetimeSeconds` on a ticket or
+    a link, each held to S3's seven days. What a stored object carries,
+    `object` on a ticket or a write: tags (how an object gets a time to live,
+    through a lifecycle rule), metadata, `Cache-Control` and a
+    `Content-Disposition`, all pinned in the ticket's policy. A download link
+    takes its own `contentDisposition`, to save a file under its name.
+  - `LambderUploadRunner` in `lambder/client`, the browser half: checks the
+    file against the rule, hashes it, asks for a ticket, posts it with
+    progress, tries again after a dropped, failing, timed-out or stalled
+    connection with a growing wait, asks for a new ticket when storage says
+    the old one expired, stops on an abort signal it also hands to the app's
+    own calls, and has the server confirm. A failure is a `LambderUploadError`
+    whose `reason` a screen words. It posts over XMLHttpRequest for progress,
+    and over fetch where that is all there is.
+  - `LambderMemoryUploadBucket`, the same bucket in memory, holding a post to
+    the rules S3 holds a presigned POST to and refusing with S3's statuses and
+    XML errors, so a runner takes the same path against it as against S3; and
+    `lambderMockUploadMswHandler` in `lambder/mock`, which puts it behind MSW
+    for a mock app's uploads.
+  - `LambderUploadFileFactsSchema` and `LambderUploadTicketSchema`, the zod
+    schemas of the two shapes that cross the app's own API; and
+    `checkUploadRule` and `refuseUnacceptedUpload`, for a bucket of an app's
+    own to refuse a file as Lambder's do.
+  - Three refusal codes for a file a rule does not accept:
+    `lambder/upload-empty`, `lambder/upload-type-rejected` and
+    `lambder/upload-too-large`.
+
+  See [Direct uploads](./docs/uploads.md).
+
+### Removed
+
+- **`LambderFlattenContract`.** It collapsed the chained contract into an
+  interface an app had to declare by hand for its clients' type checks to stay
+  cheap. A client that needs that now imports the contract `writeApiContract`
+  generates, which is flat by construction, and the server's own reads of its
+  contract cost it little. Replace
+  `export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}`
+  with `export type ApiContractType = typeof lambder.ApiContract`, or drop it
+  and point the clients at the generated file.
+
+### Changed
+
+- **`writeApiSignatures({ module, exportName, file })`.** It takes the module
+  that exports the instance, as `writeApiContract` does, and imports it,
+  rather than the instance and then its module again for the fresh-process
+  check. That check now runs by default; `verifyInFreshProcess: false` skips
+  it. Replace `writeApiSignatures(lambder, { file, verifyInFreshProcess: {
+  module, exportName } })` with `writeApiSignatures({ module, exportName,
+  file })`. Both generators take `module` as a path or a file URL
+  (`LambderModuleLocation`).
+- **`LambderMswModule` names `http.all` beside `http.post`.** It is the one
+  description of the msw module both mock adapters take, the API's and an
+  upload bucket's. The real `msw` module fits it as before; a hand-built
+  stand-in for it needs an `all` as well.
+
+## [8.0.2] - 2026-09-25
 
 A major, out of a review of 7.3.1. Most of it closes holes: session writes
 that could undo a logout or a password change, a login any website could

package/README.md

@@ -67,6 +67,10 @@ const company = await caller.api("getCompany", { slug: "acme" });
 - **Frontend hosting.** Serve a build from a folder, S3, R2 or any HTTP
   origin, with an app shell rendered through a build-pipeline-safe template
   engine.
+- **Direct uploads.** Files go from the browser straight to S3 on tickets
+  that pin their size, type and SHA-256, with a browser runner that hashes,
+  retries and reports progress, and a memory bucket that holds tests and the
+  mock to the same rules.
 - **Runs anywhere Lambda does.** API Gateway REST APIs (payload v1), HTTP APIs
   (payload v2) and Lambda Function URLs; the payload format is detected per
   event.
@@ -112,7 +116,7 @@ The package ships five entry points; pick by where the code runs:
 | `lambder/client` | Browser and isomorphic shared code | `LambderCaller`, `LambderApiRefusal`/`refuse`, the API contract and envelope types, `html`/`xml` tagged templates, `createLambderI18n` |
 | `lambder/mock` | Browser and Node, in development and tests | `LambderMockApp`, the mock runtime: your typed contract served from mock handlers over the real API pipeline and memory stores |
 | `lambder/testing` | Node, in tests | `lambderTestApp`: your real instance under test in this process, memory stores put under it in place, simulated browsers with typed callers in front of it, and the outcome assertions |
-| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance |
+| `lambder/build` | Node, in a build step | `writeApiSignatures`: the signature file both sides ship, written or checked from your instance; `writeApiContract`: the contract as plain types a client compiles instead of the server |
 
 Frontends and shared isomorphic packages should import from `lambder/client`
 only; the entry's module graph contains no AWS SDK, Node built-ins, or server
@@ -156,6 +160,7 @@ guide that matches what you are building. The full index lives in
 | [The API core](./docs/api-core.md) | `LambderApiPipeline`: the one pipeline the server and the mock runtime run, the store interfaces, the transports |
 | [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression, transports |
 | [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |
+| [Direct uploads](./docs/uploads.md) | Files the browser posts straight to S3 with tickets the server signs, verified before they count |
 | [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |
 | [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, on-demand languages, runtime dictionaries |
 | [The mock runtime](./docs/mock.md) | `LambderMockApp`: the typed contract served from mock handlers over the real pipeline, in the browser and in tests |
@@ -184,7 +189,7 @@ review of 7.3.1: session writes that cannot undo a logout, API calls that must
 be JSON, output schemas applied at runtime, rate limits that count IPv6 callers
 by their /64 and custom keys after the guards, idempotency keys bound to the
 request they were first sent with, and the same behavior on every gateway and
-in the mock. Every break and what to do about it is in the 8.0.1 entry. The
+in the mock. Every break and what to do about it is in the 8.0.2 entry. The
 compiler finds most of them. Fourteen it cannot are named there: hand-built
 calls without a JSON Content-Type, hand-built answers without `apiVersion`,
 handlers whose payload does not match their output schema, code that decoded

package/dist/build/ContractTypePrinter.d.ts

@@ -0,0 +1,85 @@
+import type ts from "typescript";
+/** How the printed module is punctuated. */
+export type ContractPrintStyle = {
+    quote: "'" | "\"";
+    semicolon: "" | ";";
+};
+/** The contract as text: each entry by name, and the named types the entries refer to. */
+export type PrintedContract = {
+    entries: {
+        name: string;
+        text: string;
+    }[];
+    declarations: {
+        name: string;
+        text: string;
+    }[];
+    /** Where the contract holds something with no plain form, and what it is. */
+    failures: string[];
+};
+export declare class ContractTypePrinter {
+    private readonly ts;
+    private readonly program;
+    private readonly checker;
+    private readonly style;
+    private readonly failures;
+    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
+    private readonly declarations;
+    /** Names a declaration may not take: the default library's, and the contract's own. */
+    private readonly takenNames;
+    /** The anonymous types being printed: meeting one again inside itself is recursion, and it needs a name. */
+    private readonly inProgress;
+    /** Under exactOptionalPropertyTypes an optional member's type carries the compiler's own "missing" undefined, which its source never wrote. */
+    private readonly exactOptionalProperties;
+    constructor(ts: typeof import("typescript"), program: ts.Program, checker: ts.TypeChecker, style: ContractPrintStyle, contractName: string);
+    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    printContract(contract: ts.Type): PrintedContract;
+    /**
+     * `label value`, with a union too long for one line starting on the next
+     * line, one member per line: what a property, an index signature and a
+     * declaration all print through.
+     */
+    labeledValue(label: string, value: string): string;
+    private print;
+    /** A union, an intersection or an object: printed in place, or as a reference to a declaration of its own. */
+    private printComposite;
+    /** The name a type is declared under, when it is one to print as a declaration: non-generic, and not the default library's. */
+    private declaredNameOf;
+    /** The name a symbol is declared under, read off its declaration, so `export default interface Customer` is Customer; undefined when it has none to print. */
+    private nameOf;
+    /**
+     * A name for a type that refers to itself and has none of its own: what it
+     * instantiates followed by its arguments (a JSON mapping of a Tree is
+     * `JsonOfTree`, a `Tree<string>` is `TreeString`), or `RecursiveType`.
+     */
+    private recursiveNameOf;
+    private printStructure;
+    private printUnion;
+    private printUnionOf;
+    private printIntersection;
+    private printObject;
+    private printMembers;
+    /**
+     * An optional member's type as its source wrote it. Under
+     * exactOptionalPropertyTypes the compiler adds its own "missing"
+     * undefined, a different type from the `undefined` a source writes;
+     * printed as `| undefined` it would let the member be undefined, which
+     * the source does not.
+     */
+    private printOptionalMember;
+    private printTuple;
+    private printTemplateLiteral;
+    /** Why a property cannot be printed as a plain member, or undefined when it can. */
+    private unprintableProperty;
+    /** An object type printed member by member: not an array, a tuple, a function or a default library interface. */
+    private isPlainObject;
+    private isCallable;
+    private isDefaultLibraryInterface;
+    /** Declared in the default library, even where a package augments it (as @types/node does some globals). */
+    private isDefaultLibrary;
+    private wrapped;
+    keyOf(name: string): string;
+    private quoted;
+    private takeName;
+    private fail;
+}

package/dist/build/ContractTypePrinter.js

@@ -0,0 +1,402 @@
+const INDENT = "    ";
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/** How long a union may run on one line before each member goes on a line of its own. */
+const UNION_LINE_WIDTH = 80;
+const atom = (text) => ({ text, compound: false });
+const indentFollowingLines = (text, indent) => text.replace(/\n/g, `\n${indent}`);
+/** Code-unit order, so the output never depends on the locale it is generated under. */
+const byCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/**
+ * Properties in the order they are written in the source: the file, then the
+ * position, then the name for those declared together (a Record's keys) or
+ * not at all. The compiler's own order is not used, because the properties of
+ * a mapped type (every zod inference) follow a union of their keys, and a
+ * union is ordered by when each key's type was first created, which moves
+ * whenever unrelated code is checked in another order.
+ */
+const bySourceOrder = (a, b) => {
+    const first = a.declarations?.[0];
+    const second = b.declarations?.[0];
+    if (first && second) {
+        const byFile = byCodeUnits(first.getSourceFile().fileName, second.getSourceFile().fileName);
+        if (byFile)
+            return byFile;
+        if (first.pos !== second.pos)
+            return first.pos - second.pos;
+    }
+    else if (first || second) {
+        return first ? -1 : 1;
+    }
+    return byCodeUnits(a.name, b.name);
+};
+/** Union members in a stable order, with null and undefined last as they are usually written. */
+const unionMemberRank = (text) => text === "null" ? 1 : text === "undefined" ? 2 : 0;
+export class ContractTypePrinter {
+    ts;
+    program;
+    checker;
+    style;
+    failures = [];
+    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
+    declarations = new Map();
+    /** Names a declaration may not take: the default library's, and the contract's own. */
+    takenNames = new Set();
+    /** The anonymous types being printed: meeting one again inside itself is recursion, and it needs a name. */
+    inProgress = new Set();
+    /** Under exactOptionalPropertyTypes an optional member's type carries the compiler's own "missing" undefined, which its source never wrote. */
+    exactOptionalProperties;
+    constructor(ts, program, checker, style, contractName) {
+        this.ts = ts;
+        this.program = program;
+        this.checker = checker;
+        this.style = style;
+        this.takenNames.add(contractName);
+        this.exactOptionalProperties = !!program.getCompilerOptions().exactOptionalPropertyTypes;
+        // A declaration named after a global the printed text refers to by
+        // name (Date) would shadow it.
+        for (const sourceFile of program.getSourceFiles()) {
+            if (!program.isSourceFileDefaultLibrary(sourceFile))
+                continue;
+            for (const statement of sourceFile.statements) {
+                if ((ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isModuleDeclaration(statement))
+                    && statement.name && ts.isIdentifier(statement.name))
+                    this.takenNames.add(statement.name.text);
+            }
+        }
+    }
+    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    printContract(contract) {
+        const entries = this.checker.getPropertiesOfType(contract)
+            .map((entry) => ({ name: entry.name, text: this.print(this.checker.getTypeOfSymbol(entry), this.keyOf(entry.name)).text }))
+            .sort((a, b) => byCodeUnits(a.name, b.name));
+        const declarations = [...this.declarations.values()]
+            .map(({ name, text }) => ({ name, text: text ?? "never" }))
+            .sort((a, b) => byCodeUnits(a.name, b.name));
+        return { entries, declarations, failures: this.failures };
+    }
+    /**
+     * `label value`, with a union too long for one line starting on the next
+     * line, one member per line: what a property, an index signature and a
+     * declaration all print through.
+     */
+    labeledValue(label, value) {
+        return value.startsWith("| ") ? `${label}\n${INDENT}${indentFollowingLines(value, INDENT)}` : `${label} ${value}`;
+    }
+    print(type, path) {
+        const { TypeFlags } = this.ts;
+        const flags = type.flags;
+        // The compiler's own `any` is the one a source wrote (or inferred);
+        // any other is the error type a compile error leaves behind.
+        if (flags & TypeFlags.Any) {
+            return type === this.checker.getAnyType() ? atom("any") : this.fail(path, "a type the compiler could not resolve, which a compile error in the app's sources leaves behind: run its typecheck");
+        }
+        if (flags & TypeFlags.Unknown)
+            return atom("unknown");
+        if (flags & TypeFlags.Never)
+            return atom("never");
+        if (flags & TypeFlags.String)
+            return atom("string");
+        if (flags & TypeFlags.Number)
+            return atom("number");
+        if (flags & TypeFlags.BigInt)
+            return atom("bigint");
+        if (flags & TypeFlags.Boolean)
+            return atom("boolean");
+        if (flags & TypeFlags.Void)
+            return atom("void");
+        if (flags & TypeFlags.Undefined)
+            return atom("undefined");
+        if (flags & TypeFlags.Null)
+            return atom("null");
+        if (flags & TypeFlags.ESSymbol)
+            return atom("symbol");
+        if (flags & TypeFlags.NonPrimitive)
+            return atom("object");
+        // Before the literals: an enum member is a literal type as well.
+        if (flags & TypeFlags.EnumLike)
+            return this.fail(path, `${this.checker.typeToString(type)}, an enum, which only its declaration can name`);
+        if (flags & TypeFlags.StringLiteral)
+            return atom(this.quoted(type.value));
+        if (flags & TypeFlags.NumberLiteral)
+            return atom(String(type.value));
+        if (flags & TypeFlags.BigIntLiteral) {
+            const { negative, base10Value } = type.value;
+            return atom(`${negative ? "-" : ""}${base10Value}n`);
+        }
+        if (flags & TypeFlags.BooleanLiteral)
+            return atom(this.checker.typeToString(type));
+        if (flags & TypeFlags.UniqueESSymbol)
+            return this.fail(path, "a unique symbol, which only its declaration can name");
+        if (flags & TypeFlags.TemplateLiteral)
+            return this.printTemplateLiteral(type, path);
+        if (flags & TypeFlags.StringMapping) {
+            const mapping = type;
+            return atom(`${mapping.symbol.name}<${this.print(mapping.type, path).text}>`);
+        }
+        if (flags & (TypeFlags.Union | TypeFlags.Intersection | TypeFlags.Object))
+            return this.printComposite(type, path);
+        return this.fail(path, `${this.checker.typeToString(type)}, which only resolves where it was written (a type parameter, or a conditional or indexed type over one)`);
+    }
+    /** A union, an intersection or an object: printed in place, or as a reference to a declaration of its own. */
+    printComposite(type, path) {
+        const known = this.declarations.get(type);
+        if (known)
+            return atom(known.name);
+        const ownName = this.declaredNameOf(type);
+        if (ownName !== undefined) {
+            // Registered before the body is printed, so a reference to itself
+            // inside the body finds the name.
+            const declaration = { name: this.takeName(ownName), text: null };
+            this.declarations.set(type, declaration);
+            declaration.text = this.printStructure(type, path).text;
+            return atom(declaration.name);
+        }
+        if (this.inProgress.has(type)) {
+            const declaration = { name: this.takeName(this.recursiveNameOf(type)), text: null };
+            this.declarations.set(type, declaration);
+            return atom(declaration.name);
+        }
+        this.inProgress.add(type);
+        const printed = this.printStructure(type, path);
+        this.inProgress.delete(type);
+        // Named while its body was being printed: it refers to itself.
+        const recursive = this.declarations.get(type);
+        if (!recursive)
+            return printed;
+        recursive.text = printed.text;
+        return atom(recursive.name);
+    }
+    /** The name a type is declared under, when it is one to print as a declaration: non-generic, and not the default library's. */
+    declaredNameOf(type) {
+        const { ObjectFlags, TypeFlags } = this.ts;
+        if (type.aliasSymbol) {
+            return type.aliasTypeArguments?.length || this.isDefaultLibrary(type.aliasSymbol) ? undefined : this.nameOf(type.aliasSymbol);
+        }
+        if (!(type.flags & TypeFlags.Object))
+            return undefined;
+        const objectFlags = type.objectFlags;
+        if (!(objectFlags & (ObjectFlags.Interface | ObjectFlags.Class)))
+            return undefined;
+        // A class, or an interface with a base type, is a reference to itself
+        // (for its `this` type). A generic one's instances are references to
+        // it instead, and are printed in place.
+        if (objectFlags & ObjectFlags.Reference && (type.target !== type || type.typeParameters?.length))
+            return undefined;
+        return this.isDefaultLibrary(type.symbol) ? undefined : this.nameOf(type.symbol);
+    }
+    /** The name a symbol is declared under, read off its declaration, so `export default interface Customer` is Customer; undefined when it has none to print. */
+    nameOf(symbol) {
+        const declaration = symbol.declarations?.[0];
+        const declared = declaration && this.ts.getNameOfDeclaration(declaration);
+        const name = declared && this.ts.isIdentifier(declared) ? declared.text : symbol.name;
+        return IDENTIFIER.test(name) && name !== "default" && !name.startsWith("__") ? name : undefined;
+    }
+    /**
+     * A name for a type that refers to itself and has none of its own: what it
+     * instantiates followed by its arguments (a JSON mapping of a Tree is
+     * `JsonOfTree`, a `Tree<string>` is `TreeString`), or `RecursiveType`.
+     */
+    recursiveNameOf(type) {
+        const { ObjectFlags, TypeFlags } = this.ts;
+        let instantiated;
+        if (type.aliasSymbol) {
+            instantiated = { symbol: type.aliasSymbol, typeArguments: type.aliasTypeArguments ?? [] };
+        }
+        else if (type.flags & TypeFlags.Object && type.objectFlags & ObjectFlags.Reference) {
+            const { target } = type;
+            const typeArguments = this.checker.getTypeArguments(type).slice(0, target.typeParameters?.length ?? 0);
+            instantiated = { symbol: target.symbol, typeArguments };
+        }
+        const base = instantiated && this.nameOf(instantiated.symbol);
+        if (!instantiated || !base)
+            return "RecursiveType";
+        const argumentNames = instantiated.typeArguments
+            .map((argument) => (argument.aliasSymbol && this.nameOf(argument.aliasSymbol)) ?? (argument.symbol && this.nameOf(argument.symbol)) ?? this.checker.typeToString(argument))
+            .filter((name) => IDENTIFIER.test(name));
+        return `${base}${argumentNames.map((name) => name[0].toUpperCase() + name.slice(1)).join("")}`;
+    }
+    printStructure(type, path) {
+        const { TypeFlags } = this.ts;
+        if (type.flags & TypeFlags.Union)
+            return this.printUnion(type, path);
+        if (type.flags & TypeFlags.Intersection)
+            return this.printIntersection(type, path);
+        return this.printObject(type, path);
+    }
+    printUnion(type, path) {
+        return this.printUnionOf(type.types, path);
+    }
+    printUnionOf(types, path) {
+        const members = [];
+        // boolean is the union of its two literals, and a union holding it
+        // holds them flattened in: they are put back together.
+        const booleans = new Set();
+        for (const member of types) {
+            if (member.flags & this.ts.TypeFlags.BooleanLiteral)
+                booleans.add(this.checker.typeToString(member));
+            else
+                members.push(this.print(member, path).text);
+        }
+        if (booleans.size === 2)
+            members.push("boolean");
+        else
+            members.push(...booleans);
+        members.sort((a, b) => unionMemberRank(a) - unionMemberRank(b) || byCodeUnits(a, b));
+        const oneLine = members.join(" | ");
+        if (oneLine.length <= UNION_LINE_WIDTH && !oneLine.includes("\n"))
+            return { text: oneLine, compound: true };
+        return { text: members.map((member) => `| ${indentFollowingLines(member, "  ")}`).join("\n"), compound: true };
+    }
+    printIntersection(type, path) {
+        // Objects intersected are one object, and printed as the one they are.
+        if (type.types.every((member) => this.isPlainObject(member)))
+            return this.printMembers(type, path);
+        const members = type.types.map((member) => this.wrapped(this.print(member, path))).sort(byCodeUnits);
+        return { text: members.join(" & "), compound: true };
+    }
+    printObject(type, path) {
+        const { checker, ts } = this;
+        if (checker.isTupleType(type))
+            return this.printTuple(type, path);
+        if (checker.isArrayType(type)) {
+            const reference = type;
+            const element = this.print(checker.getTypeArguments(reference)[0], `${path}[]`);
+            const readonly = reference.target.symbol?.escapedName === "ReadonlyArray";
+            return { text: `${readonly ? "readonly " : ""}${this.wrapped(element)}[]`, compound: readonly };
+        }
+        if (this.isCallable(type))
+            return this.fail(path, `${checker.typeToString(type)}, a function, which is not data`);
+        if (this.isDefaultLibraryInterface(type)) {
+            const reference = type;
+            const parameterCount = type.objectFlags & ts.ObjectFlags.Reference ? reference.target.typeParameters?.length ?? 0 : 0;
+            const typeArguments = parameterCount ? checker.getTypeArguments(reference).slice(0, parameterCount) : [];
+            const name = checker.getFullyQualifiedName(type.symbol);
+            return atom(typeArguments.length ? `${name}<${typeArguments.map((argument) => this.print(argument, path).text).join(", ")}>` : name);
+        }
+        return this.printMembers(type, path);
+    }
+    printMembers(type, path) {
+        const { checker, ts } = this;
+        const lines = [];
+        for (const index of checker.getIndexInfosOfType(type)) {
+            const key = this.print(index.keyType, `${path}[key]`).text;
+            lines.push(this.labeledValue(`${index.isReadonly ? "readonly " : ""}[key: ${key}]:`, this.print(index.type, `${path}[${key}]`).text));
+        }
+        for (const property of [...checker.getPropertiesOfType(type)].sort(bySourceOrder)) {
+            const propertyPath = `${path}.${property.name}`;
+            const unprintable = this.unprintableProperty(property);
+            if (unprintable) {
+                this.fail(propertyPath, unprintable);
+                continue;
+            }
+            const optional = !!(property.flags & ts.SymbolFlags.Optional);
+            const printed = optional ? this.printOptionalMember(checker.getTypeOfSymbol(property), propertyPath) : this.print(checker.getTypeOfSymbol(property), propertyPath);
+            lines.push(this.labeledValue(`${this.keyOf(property.name)}${optional ? "?" : ""}:`, printed.text));
+        }
+        if (!lines.length)
+            return atom("{}");
+        return atom(`{\n${lines.map((line) => INDENT + indentFollowingLines(line, INDENT) + this.style.semicolon).join("\n")}\n}`);
+    }
+    /**
+     * An optional member's type as its source wrote it. Under
+     * exactOptionalPropertyTypes the compiler adds its own "missing"
+     * undefined, a different type from the `undefined` a source writes;
+     * printed as `| undefined` it would let the member be undefined, which
+     * the source does not.
+     */
+    printOptionalMember(type, path) {
+        if (!this.exactOptionalProperties || !(type.flags & this.ts.TypeFlags.Union))
+            return this.print(type, path);
+        const undefinedType = this.checker.getUndefinedType();
+        const written = type.types.filter((member) => !(member.flags & this.ts.TypeFlags.Undefined) || member === undefinedType);
+        if (written.length === type.types.length)
+            return this.print(type, path);
+        return written.length === 1 ? this.print(written[0], path) : this.printUnionOf(written, path);
+    }
+    printTuple(type, path) {
+        const { ElementFlags } = this.ts;
+        const { elementFlags, labeledElementDeclarations, readonly } = type.target;
+        const labelOf = (index) => {
+            const declaration = labeledElementDeclarations?.[index];
+            return declaration && this.ts.isIdentifier(declaration.name) ? declaration.name.text : undefined;
+        };
+        // Labels are all or nothing in a tuple.
+        const labeled = elementFlags.every((_, index) => labelOf(index) !== undefined);
+        const elements = this.checker.getTypeArguments(type).slice(0, elementFlags.length).map((element, index) => {
+            const flag = elementFlags[index];
+            const printed = this.print(element, `${path}[${index}]`);
+            const label = labeled ? `${labelOf(index)}` : "";
+            if (flag & ElementFlags.Rest)
+                return `...${label ? `${label}: ` : ""}${this.wrapped(printed)}[]`;
+            if (flag & ElementFlags.Variadic)
+                return `...${label ? `${label}: ` : ""}${printed.text}`;
+            if (flag & ElementFlags.Optional)
+                return label ? `${label}?: ${printed.text}` : `${this.wrapped(printed)}?`;
+            return label ? `${label}: ${printed.text}` : printed.text;
+        });
+        return { text: `${readonly ? "readonly " : ""}[${elements.join(", ")}]`, compound: readonly };
+    }
+    printTemplateLiteral(type, path) {
+        // A cooked text as template source: JSON's escapes, plus the two a template adds.
+        const escape = (text) => JSON.stringify(text).slice(1, -1).replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+        const spans = type.types.map((span, index) => `\${${this.print(span, path).text}}${escape(type.texts[index + 1])}`);
+        return atom(`\`${escape(type.texts[0])}${spans.join("")}\``);
+    }
+    /** Why a property cannot be printed as a plain member, or undefined when it can. */
+    unprintableProperty(property) {
+        const { ts } = this;
+        if (String(property.escapedName).startsWith("__@"))
+            return "a symbol-keyed property, which only its declaration can name";
+        if (property.name.startsWith("#"))
+            return "a private field of a class, which only its declaration can hold";
+        const hidden = property.declarations?.some((declaration) => ts.getCombinedModifierFlags(declaration) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected));
+        return hidden ? "a private or protected member of a class, which only its declaration can hold" : undefined;
+    }
+    /** An object type printed member by member: not an array, a tuple, a function or a default library interface. */
+    isPlainObject(type) {
+        return !!(type.flags & this.ts.TypeFlags.Object)
+            && !this.checker.isArrayType(type) && !this.checker.isTupleType(type)
+            && !this.isCallable(type) && !this.isDefaultLibraryInterface(type);
+    }
+    isCallable(type) {
+        const { SignatureKind } = this.ts;
+        return this.checker.getSignaturesOfType(type, SignatureKind.Call).length > 0 || this.checker.getSignaturesOfType(type, SignatureKind.Construct).length > 0;
+    }
+    isDefaultLibraryInterface(type) {
+        const { SymbolFlags } = this.ts;
+        return !!type.symbol && !!(type.symbol.flags & (SymbolFlags.Interface | SymbolFlags.Class)) && this.isDefaultLibrary(type.symbol);
+    }
+    /** Declared in the default library, even where a package augments it (as @types/node does some globals). */
+    isDefaultLibrary(symbol) {
+        return !!symbol.declarations?.some((declaration) => this.program.isSourceFileDefaultLibrary(declaration.getSourceFile()));
+    }
+    wrapped(printed) {
+        if (!printed.compound)
+            return printed.text;
+        if (printed.text.startsWith("| "))
+            return `(\n${INDENT}${indentFollowingLines(printed.text, INDENT)}\n)`;
+        return `(${printed.text})`;
+    }
+    keyOf(name) {
+        return IDENTIFIER.test(name) ? name : this.quoted(name);
+    }
+    quoted(value) {
+        const doubleQuoted = JSON.stringify(value);
+        if (this.style.quote === "\"")
+            return doubleQuoted;
+        // Every double quote inside is escaped, so each \" is a quote and
+        // never the tail of an escaped backslash.
+        return `'${doubleQuoted.slice(1, -1).replace(/\\"/g, "\"").replace(/'/g, "\\'")}'`;
+    }
+    takeName(base) {
+        let name = base;
+        for (let suffix = 2; this.takenNames.has(name); suffix++)
+            name = `${base}${suffix}`;
+        this.takenNames.add(name);
+        return name;
+    }
+    fail(path, reason) {
+        this.failures.push(`${path}: ${reason}`);
+        return atom("unknown");
+    }
+}

package/dist/build/moduleLocation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The module a generator reads the instance from, as both of lambder/build's
+ * generators take it: a path relative to the working directory, or a file
+ * URL, as a URL (`new URL("../server/index.ts", import.meta.url)`) or as the
+ * string `import.meta.resolve()` answers.
+ */
+export type LambderModuleLocation = string | 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 declare const moduleUrlOf: (module: LambderModuleLocation) => string;
+/** The module as a path on disk. */
+export declare const modulePathOf: (module: LambderModuleLocation) => string;