lambder 8.1.1 → 8.1.2

package/CHANGELOG.md

@@ -9,6 +9,34 @@ 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.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

package/dist/build/ContractTypePrinter.d.ts

@@ -22,18 +22,40 @@ export declare class ContractTypePrinter {
     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;
+    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 takenNames;
+    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. */
+    /**
+     * 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
@@ -43,16 +65,25 @@ export declare class ContractTypePrinter {
     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;
+    /** 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 recursiveNameOf;
+    private recursiveDeclarationOf;
     private printStructure;
     private printUnion;
     private printUnionOf;
@@ -80,6 +111,5 @@ export declare class ContractTypePrinter {
     private wrapped;
     keyOf(name: string): string;
     private quoted;
-    private takeName;
     private fail;
 }

package/dist/build/ContractTypePrinter.js

@@ -37,10 +37,12 @@ export class ContractTypePrinter {
     checker;
     style;
     failures = [];
-    /** Every named declaration by the type it stands for; its text is null while it is being printed. */
+    /** Every declaration by the type it stands for. */
     declarations = new Map();
+    /** The name each declaration is printed under, settled from all of them; empty on the pass that finds them. */
+    settledNames = new Map();
     /** Names a declaration may not take: the default library's, and the contract's own. */
-    takenNames = new Set();
+    reservedNames = 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. */
@@ -50,7 +52,7 @@ export class ContractTypePrinter {
         this.program = program;
         this.checker = checker;
         this.style = style;
-        this.takenNames.add(contractName);
+        this.reservedNames.add(contractName);
         this.exactOptionalProperties = !!program.getCompilerOptions().exactOptionalPropertyTypes;
         // A declaration named after a global the printed text refers to by
         // name (Date) would shadow it.
@@ -60,20 +62,65 @@ export class ContractTypePrinter {
             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);
+                    this.reservedNames.add(statement.name.text);
             }
         }
     }
-    /** Prints each member of the contract type, sorted by name, and every declaration they refer to. */
+    /**
+     * 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) {
-        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 members = [...this.checker.getPropertiesOfType(contract)].sort((a, b) => byCodeUnits(a.name, b.name));
+        const printEntries = () => members.map((entry) => ({ name: entry.name, text: this.print(this.checker.getTypeOfSymbol(entry), this.keyOf(entry.name)).text }));
+        printEntries();
+        this.settledNames = this.settleNames();
+        this.failures = [];
+        this.declarations = new Map();
+        const entries = printEntries();
         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 };
     }
+    /**
+     * 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.
+     */
+    settleNames() {
+        const wanting = [...this.declarations].sort(([, a], [, b]) => byCodeUnits(a.base, b.base) || byCodeUnits(a.origin, b.origin));
+        const taken = new Set(this.reservedNames);
+        const settled = new Map();
+        const numbered = [];
+        for (const [type, { base }] of wanting) {
+            if (taken.has(base)) {
+                numbered.push([type, base]);
+                continue;
+            }
+            taken.add(base);
+            settled.set(type, base);
+        }
+        for (const [type, base] of numbered) {
+            let suffix = 2;
+            while (taken.has(`${base}${suffix}`))
+                suffix++;
+            taken.add(`${base}${suffix}`);
+            settled.set(type, `${base}${suffix}`);
+        }
+        return settled;
+    }
     /**
      * `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
@@ -142,20 +189,16 @@ export class ContractTypePrinter {
         const known = this.declarations.get(type);
         if (known)
             return atom(known.name);
-        const ownName = this.declaredNameOf(type);
-        if (ownName !== undefined) {
+        const own = this.ownDeclarationOf(type);
+        if (own) {
             // 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);
+            const declaration = this.declare(type, own);
             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);
-        }
+        if (this.inProgress.has(type))
+            return atom(this.declare(type, this.recursiveDeclarationOf(type)).name);
         this.inProgress.add(type);
         const printed = this.printStructure(type, path);
         this.inProgress.delete(type);
@@ -166,11 +209,17 @@ export class ContractTypePrinter {
         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) {
+    /** A type's declaration, under the name it is settled to once the first pass has settled them. */
+    declare(type, { base, origin }) {
+        const declaration = { base, origin, name: this.settledNames.get(type) ?? base, text: null };
+        this.declarations.set(type, declaration);
+        return declaration;
+    }
+    /** 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. */
+    ownDeclarationOf(type) {
         const { ObjectFlags, TypeFlags } = this.ts;
         if (type.aliasSymbol) {
-            return type.aliasTypeArguments?.length || this.isDefaultLibrary(type.aliasSymbol) ? undefined : this.nameOf(type.aliasSymbol);
+            return type.aliasTypeArguments?.length || this.isDefaultLibrary(type.aliasSymbol) ? undefined : this.declaredAs(type.aliasSymbol);
         }
         if (!(type.flags & TypeFlags.Object))
             return undefined;
@@ -182,7 +231,17 @@ export class ContractTypePrinter {
         // 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);
+        return this.isDefaultLibrary(type.symbol) ? undefined : this.declaredAs(type.symbol);
+    }
+    /** A symbol's name to declare a type under, and where the symbol is declared. */
+    declaredAs(symbol) {
+        const base = this.nameOf(symbol);
+        return base === undefined ? undefined : { base, origin: this.originOf(symbol) };
+    }
+    /** Where a symbol is declared, as text that orders by file and then position; empty for one declared nowhere. */
+    originOf(symbol) {
+        const declaration = symbol?.declarations?.[0];
+        return declaration ? `${declaration.getSourceFile().fileName}\0${String(declaration.pos).padStart(10, "0")}` : "";
     }
     /** 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) {
@@ -195,8 +254,11 @@ export class ContractTypePrinter {
      * 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.
      */
-    recursiveNameOf(type) {
+    recursiveDeclarationOf(type) {
         const { ObjectFlags, TypeFlags } = this.ts;
         let instantiated;
         if (type.aliasSymbol) {
@@ -209,11 +271,14 @@ export class ContractTypePrinter {
         }
         const base = instantiated && this.nameOf(instantiated.symbol);
         if (!instantiated || !base)
-            return "RecursiveType";
+            return { base: "RecursiveType", origin: this.originOf(type.symbol) };
         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("")}`;
+        return {
+            base: `${base}${argumentNames.map((name) => name[0].toUpperCase() + name.slice(1)).join("")}`,
+            origin: [instantiated.symbol, ...instantiated.typeArguments.map((argument) => argument.aliasSymbol ?? argument.symbol)].map((symbol) => this.originOf(symbol)).join("\n"),
+        };
     }
     printStructure(type, path) {
         const { TypeFlags } = this.ts;
@@ -388,13 +453,6 @@ export class ContractTypePrinter {
         // 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/writeApiContract.d.ts

@@ -47,7 +47,8 @@ export type LambderApiContractFileResult = {
  * 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.
+ * own that the entries refer to; two that want one name are numbered by where
+ * each is declared, never by the order the APIs were registered in.
  *
  * 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

package/dist/build/writeApiContract.js

@@ -24,7 +24,8 @@ const DIAGNOSTIC_LIMIT = 20;
  * 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.
+ * own that the entries refer to; two that want one name are numbered by where
+ * each is declared, never by the order the APIs were registered in.
  *
  * 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

package/dist/client/LambderUploadRunner.d.ts

@@ -48,10 +48,10 @@ export type LambderUploadRunnerOptions<Reference, Receipt> = {
     /**
      * How storage is tried again when it cannot be reached, stalls, or answers
      * a failure a retry can cure (a 5xx, RequestTimeout, SlowDown). Each wait
-     * is a random time between `baseDelayMs` and a ceiling that doubles with
-     * every failed attempt, never past `maxDelayMs`, so many browsers dropped
-     * together do not come back in step. Default: 4 attempts, waits from one
-     * second to 15.
+     * is a random time between `baseDelayMs` and a ceiling of twice that,
+     * doubling with every failed attempt and never past `maxDelayMs`, so many
+     * browsers dropped together do not come back in step, not even the first
+     * time. Default: 4 attempts, waits from one second to 15.
      */
     storageRetry?: {
         attempts?: number;

package/dist/client/LambderUploadRunner.js

@@ -59,18 +59,16 @@ export class LambderUploadRunner {
         };
         stopIfCancelled();
         report("hashing");
-        let bytes;
-        try {
-            bytes = new Uint8Array(await file.arrayBuffer());
-        }
-        catch (cause) {
-            throw new LambderUploadError("fileUnreadable", { cause });
-        }
         const fileFacts = {
             fileName: file.name,
             mimeType: file.type,
             byteSize: file.size,
-            sha256Base64: await sha256Base64Of(bytes),
+            // Read straight into the digest, never into a variable: the buffer
+            // is the size of the file, and a local would keep it through
+            // every await of the upload that follows.
+            sha256Base64: await sha256Base64Of(new Uint8Array(await file.arrayBuffer().catch((cause) => {
+                throw new LambderUploadError("fileUnreadable", { cause });
+            }))),
         };
         stopIfCancelled();
         const requestTicket = async () => {
@@ -120,7 +118,7 @@ export class LambderUploadRunner {
         await this.options.discardUpload?.(receipt);
     }
     waitBeforeRetry(failedAttempts, signal) {
-        const ceiling = Math.max(this.baseDelayMs, Math.min(this.baseDelayMs * 2 ** (failedAttempts - 1), this.maxDelayMs));
+        const ceiling = Math.max(this.baseDelayMs, Math.min(this.baseDelayMs * 2 ** failedAttempts, this.maxDelayMs));
         return new Promise((resolve, reject) => {
             if (signal?.aborted)
                 return reject(new LambderUploadError("cancelled"));
@@ -218,8 +216,10 @@ const xmlText = (text) => text.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (entity, na
 /**
  * Storage explains a refusal in XML, `<Error><Code/><Message/></Error>`,
  * read here without a DOM so the runner works wherever fetch does. A
- * transient code is tried again like a dropped connection, and an expired
- * ticket is the one refusal a new ticket cures.
+ * transient code is tried again like a dropped connection. An expired ticket
+ * is the one refusal a new ticket cures, and so is ExpiredToken: the
+ * temporary credentials that signed the ticket ran out before it did, and
+ * the next one is signed with fresh ones.
  */
 const rejectedOutcome = (status, body) => {
     const code = xmlText(/<Code>([^<]*)<\/Code>/.exec(body)?.[1] ?? "") || `HTTP ${status}`;
@@ -228,7 +228,7 @@ const rejectedOutcome = (status, body) => {
         return { kind: "unreachable" };
     return {
         kind: "rejected",
-        ticketExpired: code === "AccessDenied" && /expired/i.test(message),
+        ticketExpired: code === "ExpiredToken" || (code === "AccessDenied" && /expired/i.test(message)),
         detail: message ? `${code}: ${message}` : code,
     };
 };

package/dist/shared/util/escapeXmlText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Text made safe to place inside an XML element or a quoted attribute: the
+ * five characters XML gives meaning to become numeric references. For the
+ * small documents storage speaks, a tag set a ticket carries and an error a
+ * memory bucket answers with, which LambderHtml's `xml` template would also
+ * escape but no module in wire/ may import.
+ */
+export declare const escapeXmlText: (text: string) => string;

package/dist/shared/util/escapeXmlText.js

@@ -0,0 +1,8 @@
+/**
+ * Text made safe to place inside an XML element or a quoted attribute: the
+ * five characters XML gives meaning to become numeric references. For the
+ * small documents storage speaks, a tag set a ticket carries and an error a
+ * memory bucket answers with, which LambderHtml's `xml` template would also
+ * escape but no module in wire/ may import.
+ */
+export const escapeXmlText = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);

package/dist/shared/wire/LambderUploadObjectFields.js

@@ -1,5 +1,5 @@
 import { contentDispositionHeader } from "../util/LambderContentDisposition.js";
-const escapeXml = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);
+import { escapeXmlText } from "../util/escapeXmlText.js";
 /**
  * What a ticket's form carries for the stored object, in the fields S3's
  * presigned POST reads them from: the tag set as the XML `tagging` field,
@@ -12,7 +12,7 @@ export const uploadObjectFormFields = (object) => {
     const fields = {};
     const tags = Object.entries(object?.tags ?? {});
     if (tags.length) {
-        fields.tagging = `<Tagging><TagSet>${tags.map(([key, value]) => `<Tag><Key>${escapeXml(key)}</Key><Value>${escapeXml(value)}</Value></Tag>`).join("")}</TagSet></Tagging>`;
+        fields.tagging = `<Tagging><TagSet>${tags.map(([key, value]) => `<Tag><Key>${escapeXmlText(key)}</Key><Value>${escapeXmlText(value)}</Value></Tag>`).join("")}</TagSet></Tagging>`;
     }
     for (const [name, value] of Object.entries(object?.metadata ?? {}))
         fields[`x-amz-meta-${name.toLowerCase()}`] = value;

package/dist/stores/LambderMemoryUploadBucket.js

@@ -1,5 +1,6 @@
 import { assertObjectOptions, assertPinnedObjectKey, assertSignatureLifetime, } from "../shared/contracts/LambderUploadBucket.js";
 import { contentDispositionHeader } from "../shared/util/LambderContentDisposition.js";
+import { escapeXmlText } from "../shared/util/escapeXmlText.js";
 import { uploadObjectFormFields } from "../shared/wire/LambderUploadObjectFields.js";
 import { refuseUnacceptedUpload } from "../shared/wire/LambderUploadRefusal.js";
 import { sha256Base64Of } from "../shared/util/LambderTextDigest.js";
@@ -214,6 +215,5 @@ export class LambderMemoryUploadBucket {
 /** A key as a URL path: each segment escaped, the slashes kept, as S3 addresses an object. */
 const encodeObjectKey = (objectKey) => objectKey.split("/").map(encodeURIComponent).join("/");
 const decodeObjectKey = (path) => path.split("/").map(decodeURIComponent).join("/");
-const escapeXml = (text) => text.replace(/[<>&'"]/g, (character) => `&#${character.charCodeAt(0)};`);
 /** An error the way S3 writes one: the status, and `<Error><Code/><Message/></Error>` as XML. */
-const storageError = (status, code, message) => new Response(`<?xml version="1.0" encoding="UTF-8"?>\n<Error><Code>${escapeXml(code)}</Code><Message>${escapeXml(message)}</Message></Error>`, { status, headers: { "content-type": "application/xml" } });
+const storageError = (status, code, message) => new Response(`<?xml version="1.0" encoding="UTF-8"?>\n<Error><Code>${escapeXmlText(code)}</Code><Message>${escapeXmlText(message)}</Message></Error>`, { status, headers: { "content-type": "application/xml" } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "8.1.1",
+  "version": "8.1.2",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [