lambder 8.0.2 → 8.1.2

package/CHANGELOG.md

@@ -9,7 +9,149 @@ 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.2] - 2026-09-26
+
+### Fixed
+
+- **`writeApiContract` names no longer follow the order APIs are registered
+  in.** Two types that want one name (an interface `Row` in two modules) were
+  told apart by a number given in the order the printer met them, so
+  reordering registrations, or adding an API that reaches one of them first,
+  swapped `Row` and `Row2` and reported every API using either as changed.
+  The printer now finds every declaration first and numbers them by where
+  each is declared, the one declared first (by file, then position) keeping
+  the name, and a number never takes the name another type is declared
+  under. A file already written may be renamed once, the first time it is
+  written with this version.
+- **`LambderUploadRunner` randomises its first wait too.** The ceiling of the
+  first wait before trying storage again was the base itself, so browsers
+  dropped together all came back exactly `baseDelayMs` later. Each wait is
+  now between `baseDelayMs` and twice it, doubling with every failed attempt
+  up to `maxDelayMs`.
+- **`LambderUploadRunner` renews a ticket on `ExpiredToken`,** which S3
+  answers when the temporary credentials that signed the ticket ran out
+  before the ticket did. It is renewed like an expired ticket, at once and
+  spending no attempt; before, the upload failed as `storageRejected`.
+- **`LambderUploadRunner` no longer holds the file's bytes through the
+  upload.** The buffer it hashes, as large as the file, was kept in a local
+  for the whole post and every retry; it is now read straight into the
+  digest.
+
+## [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,115 @@
+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 failures;
+    /** Every declaration by the type it stands for. */
+    private declarations;
+    /** The name each declaration is printed under, settled from all of them; empty on the pass that finds them. */
+    private settledNames;
+    /** Names a declaration may not take: the default library's, and the contract's own. */
+    private readonly reservedNames;
+    /** 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.
+     *
+     * In two passes: the first finds every type that needs a declaration,
+     * and the second prints with their names settled from all of them. Named
+     * as the printer met them, two types wanting one name would trade it
+     * whenever the APIs were registered in another order, or a union's
+     * members created in another, and the file would move with no API
+     * changed.
+     */
+    printContract(contract: ts.Type): PrintedContract;
+    /**
+     * A name for every declaration the first pass found. Of the types that
+     * want one name, the one declared first (by file, then position) keeps
+     * it, and the others take the lowest free number after it once every
+     * type has claimed its own name, so a number never takes the name
+     * another type is declared under. Types declared at one place (two
+     * instantiations of a generic) keep the order the entries reached them
+     * in, by entry name.
+     */
+    private settleNames;
+    /**
+     * `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;
+    /** A type's declaration, under the name it is settled to once the first pass has settled them. */
+    private declare;
+    /** The name a type is declared under and where, when it is one to print as a declaration: non-generic, and not the default library's. */
+    private ownDeclarationOf;
+    /** A symbol's name to declare a type under, and where the symbol is declared. */
+    private declaredAs;
+    /** Where a symbol is declared, as text that orders by file and then position; empty for one declared nowhere. */
+    private originOf;
+    /** 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`.
+     * Its origin is where what it instantiates is declared, then where each
+     * argument is, so two instantiations named alike are told apart by their
+     * arguments.
+     */
+    private recursiveDeclarationOf;
+    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 fail;
+}