lambder 7.3.1 → 8.0.2

package/dist/stores/LambderMemoryIdempotencyStore.js

@@ -10,14 +10,12 @@ import { LambderExpiringMap, LambderExpiringMapFullError } from "../shared/util/
  * path can be exercised; unbounded by default. `now` is injectable so a test
  * can expire a claim without waiting.
  *
- * `maxEntries` is the map's ceiling, 100,000 by default, and it is the one
- * way this store differs from a table: a process cannot hold records without
- * bound, so past the ceiling the SETTLED records are dropped, soonest expiry
- * first, and a retry whose record was dropped executes again instead of
- * replaying. Pending claims are never dropped for room, because losing one
- * lets two concurrent retries execute at once, which is the thing idempotency
- * exists to prevent; a claim that cannot be made room for is reported as
- * "pending" instead, so the duplicate is refused rather than run.
+ * `maxEntries` (100,000 by default) is the one way this store differs from a
+ * table: past the ceiling, SETTLED records are dropped, soonest expiry first,
+ * and a retry whose record was dropped executes again instead of replaying.
+ * Pending claims are never dropped, since losing one lets two concurrent
+ * retries both execute; a claim that finds no room is reported as "pending"
+ * instead, so the duplicate is refused rather than run.
  */
 export class LambderMemoryIdempotencyStore {
     records;
@@ -34,7 +32,7 @@ export class LambderMemoryIdempotencyStore {
     nowSeconds() { return Math.floor(this.now() / 1000); }
     /** A settled record as the engine reads it: a copy, so a caller writing onto what it got back cannot rewrite the record. */
     static answerOf(record) {
-        return { statusCode: record.statusCode, headers: structuredClone(record.headers), body: record.body };
+        return { statusCode: record.statusCode, headers: structuredClone(record.headers), body: record.body, fingerprint: record.fingerprint };
     }
     async peek(scopeKey) {
         const record = this.records.get(scopeKey);
@@ -42,43 +40,45 @@ export class LambderMemoryIdempotencyStore {
             return null;
         return LambderMemoryIdempotencyStore.answerOf(record);
     }
-    async begin(scopeKey, { pendingTtlSeconds }) {
+    async begin(scopeKey, { pendingTtlSeconds, fingerprint }) {
         const existing = this.records.get(scopeKey);
         if (existing) {
             if (existing.state === "done")
                 return { state: "done", ...LambderMemoryIdempotencyStore.answerOf(existing) };
-            return { state: "pending" };
+            return { state: "pending", fingerprint: existing.fingerprint };
         }
         this.ownerCounter += 1;
         const ownerToken = `owner-${this.ownerCounter}`;
         try {
-            // Not evictable: the claim is the only thing standing between two
-            // concurrent retries and two executions, and it is also the entry
-            // the soonest-expiry rule would otherwise take first, since a
-            // claim lives for minutes and the record it becomes for a day.
-            this.records.set(scopeKey, { state: "pending", ownerToken }, this.nowSeconds() + pendingTtlSeconds, { evictable: false });
+            // Not evictable: the claim is all that stands between two
+            // concurrent retries and two executions, and the soonest-expiry
+            // rule would take it first (a claim lives minutes, a record a day).
+            this.records.set(scopeKey, { state: "pending", ownerToken, fingerprint }, this.nowSeconds() + pendingTtlSeconds, { evictable: false });
         }
         catch (error) {
             if (!(error instanceof LambderExpiringMapFullError))
                 throw error;
-            // Every record held is a live claim, so there is no room and
-            // nothing safe to take. "pending" is the interface's shape for
-            // "the claim is not yours": the caller refuses the duplicate,
-            // which is the answer that cannot execute anything twice, and a
-            // retry once the flood drains claims normally.
+            // Every record held is a live claim, so nothing is safe to take.
+            // "pending" means "the claim is not yours": the caller refuses the
+            // duplicate, which cannot execute anything twice, and a retry
+            // after the flood drains claims normally. It carries the caller's
+            // own fingerprint, so the engine answers the in-flight 409 and the
+            // client retries under the same key; any other fingerprint would
+            // be the key-reused 409, which moves a client's key scope on as
+            // though the operation were settled.
             if (!this.claimCeilingReported) {
                 this.claimCeilingReported = true;
                 console.error("LambderMemoryIdempotencyStore: every record held is a live claim, so new requests are refused as duplicates until one settles. Raise maxEntries or move to LambderDdbIdempotencyStore.");
             }
-            return { state: "pending" };
+            return { state: "pending", fingerprint };
         }
         this.claimCeilingReported = false;
         return { state: "new", ownerToken };
     }
-    async complete(scopeKey, ownerToken, { statusCode, headers, body, ttlSeconds }) {
-        // Size first, ownership second, the order LambderDdbIdempotencyStore works
-        // in: it settles with one conditional write, so the only thing it can
-        // decide before going to the table is whether the body fits.
+    async complete(scopeKey, ownerToken, { statusCode, headers, body, fingerprint, ttlSeconds }) {
+        // Size first, ownership second, as LambderDdbIdempotencyStore must:
+        // it settles with one conditional write, so whether the body fits is
+        // all it can decide before going to the table.
         if (new TextEncoder().encode(body).length > this.maxBodyBytes)
             return "too-large";
         const existing = this.records.get(scopeKey);
@@ -87,18 +87,19 @@ export class LambderMemoryIdempotencyStore {
         // Settled records ARE evictable: the claim's job is done, and a record
         // the ceiling drops costs a retry its replay, not its exclusivity.
         // The key is already held, so this write cannot cross the ceiling.
-        this.records.set(scopeKey, { state: "done", ownerToken, statusCode, headers: structuredClone(headers), body }, this.nowSeconds() + ttlSeconds);
+        this.records.set(scopeKey, { state: "done", ownerToken, statusCode, headers: structuredClone(headers), body, fingerprint }, this.nowSeconds() + ttlSeconds);
         return "stored";
     }
+    /** Releases a pending claim for its owner; a settled record stays, as LambderIdempotencyStore requires. */
     async abandon(scopeKey, ownerToken) {
         const existing = this.records.get(scopeKey);
-        if (existing && existing.ownerToken === ownerToken)
+        if (existing?.state === "pending" && existing.ownerToken === ownerToken)
             this.records.delete(scopeKey);
     }
     /**
      * The record under a scope, for assertions; null when absent or expired.
-     * A copy, like every other read here, so an assertion that pokes at what
-     * it got back cannot edit the stored record.
+     * A copy, like every read here, so an assertion cannot edit the stored
+     * record.
      */
     recordOf(scopeKey) {
         const record = this.records.get(scopeKey);

package/dist/stores/LambderMemoryRateLimiter.d.ts

@@ -9,15 +9,13 @@ import { type LambderRateLimiter, type LambderRateLimitPolicy, type LambderRateL
  * `now` is injectable so a test can move time forward and watch a window
  * reset without waiting for it.
  *
- * `maxEntries` is the ceiling on counters held at once, 100,000 by default,
- * and it is the one way this limiter differs from the table: a process cannot
- * hold counters without bound, so past the ceiling the counters closest to
- * their window's end are dropped and a key whose counter was dropped starts
- * that window again from zero. It takes one distinct key per counter to get
- * there (a limit keyed per IP under a flood from many of them), and the
- * counters with the most life left, which are the long-window ones, are the
- * last to go. A deployment where that matters wants LambderDdbRateLimiter,
- * whose counters are not held in the process at all.
+ * `maxEntries` (100,000 counters by default) is the one way this limiter
+ * differs from the table: past the ceiling, the counters closest to their
+ * window's end are dropped, and a key whose counter was dropped starts that
+ * window again from zero. Reaching it takes one distinct key per counter (a
+ * per-IP limit under a flood from many IPs), and the long-window counters,
+ * with the most life left, go last. Where that matters, use
+ * LambderDdbRateLimiter, whose counters live outside the process.
  */
 export declare class LambderMemoryRateLimiter implements LambderRateLimiter {
     private readonly counters;
@@ -26,6 +24,7 @@ export declare class LambderMemoryRateLimiter implements LambderRateLimiter {
         now?: () => number;
         maxEntries?: number;
     });
+    clockMilliseconds(): number;
     isRateLimited(trackerKey: string, policy: LambderRateLimitPolicy): Promise<LambderRateLimitResult>;
     /** The attempts counted so far for a key in the current window of `window`; for assertions. */
     countOf(trackerKey: string, window: LambderRateLimitWindow): number;

package/dist/stores/LambderMemoryRateLimiter.js

@@ -1,6 +1,6 @@
 import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
-import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
 /**
  * Fixed-window rate limiter held in memory: the same windows, the same
  * attempts-count semantics and the same evaluation order as
@@ -11,15 +11,13 @@ import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
  * `now` is injectable so a test can move time forward and watch a window
  * reset without waiting for it.
  *
- * `maxEntries` is the ceiling on counters held at once, 100,000 by default,
- * and it is the one way this limiter differs from the table: a process cannot
- * hold counters without bound, so past the ceiling the counters closest to
- * their window's end are dropped and a key whose counter was dropped starts
- * that window again from zero. It takes one distinct key per counter to get
- * there (a limit keyed per IP under a flood from many of them), and the
- * counters with the most life left, which are the long-window ones, are the
- * last to go. A deployment where that matters wants LambderDdbRateLimiter,
- * whose counters are not held in the process at all.
+ * `maxEntries` (100,000 counters by default) is the one way this limiter
+ * differs from the table: past the ceiling, the counters closest to their
+ * window's end are dropped, and a key whose counter was dropped starts that
+ * window again from zero. Reaching it takes one distinct key per counter (a
+ * per-IP limit under a flood from many IPs), and the long-window counters,
+ * with the most life left, go last. Where that matters, use
+ * LambderDdbRateLimiter, whose counters live outside the process.
  */
 export class LambderMemoryRateLimiter {
     counters;
@@ -28,6 +26,9 @@ export class LambderMemoryRateLimiter {
         this.now = options.now ?? (() => Date.now());
         this.counters = new LambderExpiringMap({ now: this.now, maxEntries: options.maxEntries });
     }
+    clockMilliseconds() {
+        return this.now();
+    }
     async isRateLimited(trackerKey, policy) {
         const nowSeconds = Math.floor(this.now() / 1000);
         for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
@@ -35,9 +36,9 @@ export class LambderMemoryRateLimiter {
             if (!limit)
                 continue;
             const windowStart = Math.floor(nowSeconds / seconds) * seconds;
-            // The table gives the tracker key and the window separate
-            // attributes; one string here has to keep them as distinct, so the
-            // fields are joined through the escaping join rather than glued.
+            // The table keeps the tracker key and the window in separate
+            // attributes; one string has to keep them as distinct, hence the
+            // escaping join.
             const counterKey = joinKeyFields(trackerKey, key, String(windowStart));
             const counter = this.counters.get(counterKey) ?? { count: 0 };
             // The DynamoDB limiter's conditional ADD: allowed while the count

package/dist/stores/LambderMemorySessionStore.d.ts

@@ -1,4 +1,4 @@
-import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderSessionChanges, LambderSessionRecord, LambderSessionStore, LambderSessionUpdateResult } from "../shared/contracts/LambderSessionStore.js";
 /**
  * Session records held in memory: a Map in place of the DynamoDB table. For
  * tests and for the mock runtime, where the session model (tokens, expiry,
@@ -7,9 +7,11 @@ import type { LambderSessionRecord, LambderSessionStore } from "../shared/contra
  *
  * Records are copied on the way in and out through JSON, the way a real store
  * serializes them, so a caller mutating a fetched record changes nothing until
- * it is put back, and data DynamoDB would reject is rejected here too. A
- * record also leaves at its own expiresAt, the way the table's TTL removes
- * it, so a long-lived process does not hold every session it ever issued.
+ * it is written back, and data DynamoDB would reject is rejected here too.
+ * Creates and updates carry the table's conditions: a create refuses an
+ * existing record, and an update never brings back a deleted one. A record
+ * also leaves at its own expiresAt, as the table's TTL removes it, so a
+ * long-lived process does not hold every session it ever issued.
  */
 export declare class LambderMemorySessionStore<SessionData = unknown> implements LambderSessionStore<SessionData> {
     /** Nothing here outlives the process. */
@@ -28,17 +30,18 @@ export declare class LambderMemorySessionStore<SessionData = unknown> implements
     private static keyOf;
     /**
      * A record the way a real store hands it back: through JSON, so an
-     * undefined field is gone and a cyclic value throws here exactly as it
-     * throws on the way into DynamoDB. structuredClone did neither, which made
-     * the memory store the more forgiving of the two and let a test pass over
-     * data the production store would reject.
+     * undefined field is gone and a cyclic value throws here exactly as on the
+     * way into DynamoDB. structuredClone would do neither, and a test could
+     * then pass over data the production store rejects.
      */
     private static storedCopy;
     get(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
-    put(record: LambderSessionRecord<SessionData>): Promise<void>;
-    delete(sessionKeyHash: string, secretHash: string): Promise<void>;
+    create(record: LambderSessionRecord<SessionData>): Promise<void>;
+    update(sessionKeyHash: string, secretHash: string, changes: LambderSessionChanges<SessionData>, condition?: {
+        dataVersion: number;
+    }): Promise<LambderSessionUpdateResult>;
+    delete(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
     listSecretHashes(sessionKeyHash: string): Promise<string[]>;
-    markDataExpired(sessionKeyHash: string, secretHash: string, at: number): Promise<void>;
     /** Every live record held, for assertions. */
     list(): LambderSessionRecord<SessionData>[];
     /** Number of live records held. */

package/dist/stores/LambderMemorySessionStore.js

@@ -1,5 +1,5 @@
 import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
-import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
 /**
  * Session records held in memory: a Map in place of the DynamoDB table. For
  * tests and for the mock runtime, where the session model (tokens, expiry,
@@ -8,9 +8,11 @@ import { joinKeyFields } from "../shared/util/LambderKeyFields.js";
  *
  * Records are copied on the way in and out through JSON, the way a real store
  * serializes them, so a caller mutating a fetched record changes nothing until
- * it is put back, and data DynamoDB would reject is rejected here too. A
- * record also leaves at its own expiresAt, the way the table's TTL removes
- * it, so a long-lived process does not hold every session it ever issued.
+ * it is written back, and data DynamoDB would reject is rejected here too.
+ * Creates and updates carry the table's conditions: a create refuses an
+ * existing record, and an update never brings back a deleted one. A record
+ * also leaves at its own expiresAt, as the table's TTL removes it, so a
+ * long-lived process does not hold every session it ever issued.
  */
 export class LambderMemorySessionStore {
     /** Nothing here outlives the process. */
@@ -26,17 +28,16 @@ export class LambderMemorySessionStore {
         this.records = new LambderExpiringMap(options);
     }
     static keyOf(sessionKeyHash, secretHash) {
-        // Escaped rather than joined plainly: both halves are hex today, but a
-        // custom LambderSessionCrypto writes whatever it likes into them, and
-        // two records sharing one key would be one session silently.
+        // Escaped rather than joined plainly: the default crypto writes hex,
+        // but a custom LambderSessionCrypto may write anything, and two
+        // records sharing one key would silently be one session.
         return joinKeyFields(sessionKeyHash, secretHash);
     }
     /**
      * A record the way a real store hands it back: through JSON, so an
-     * undefined field is gone and a cyclic value throws here exactly as it
-     * throws on the way into DynamoDB. structuredClone did neither, which made
-     * the memory store the more forgiving of the two and let a test pass over
-     * data the production store would reject.
+     * undefined field is gone and a cyclic value throws here exactly as on the
+     * way into DynamoDB. structuredClone would do neither, and a test could
+     * then pass over data the production store rejects.
      */
     static storedCopy(record) {
         return JSON.parse(JSON.stringify(record));
@@ -45,22 +46,40 @@ export class LambderMemorySessionStore {
         const record = this.records.get(LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash));
         return record ? LambderMemorySessionStore.storedCopy(record) : null;
     }
-    async put(record) {
-        this.records.set(LambderMemorySessionStore.keyOf(record.sessionKeyHash, record.secretHash), LambderMemorySessionStore.storedCopy(record), record.expiresAt);
+    async create(record) {
+        const key = LambderMemorySessionStore.keyOf(record.sessionKeyHash, record.secretHash);
+        if (this.records.get(key))
+            throw new Error("LambderMemorySessionStore: a session already exists under these hashes.");
+        this.records.set(key, LambderMemorySessionStore.storedCopy(record), record.expiresAt);
+    }
+    async update(sessionKeyHash, secretHash, changes, condition) {
+        const key = LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash);
+        const record = this.records.get(key);
+        if (!record)
+            return "missing";
+        if (condition && record.dataVersion !== condition.dataVersion)
+            return "stale";
+        // A write of the data or its deadline moves the version, whatever
+        // value it writes, as the DynamoDB store's ADD does.
+        const writesData = "data" in changes || changes.dataExpiresAt !== undefined;
+        // Through the same JSON copy a create takes, so an update carries
+        // exactly what the table would hold, and the record's own expiry
+        // moves with it, the way the table's TTL attribute does.
+        const updated = LambderMemorySessionStore.storedCopy({ ...record, ...changes, dataVersion: record.dataVersion + (writesData ? 1 : 0) });
+        this.records.set(key, updated, updated.expiresAt);
+        return "updated";
     }
     async delete(sessionKeyHash, secretHash) {
-        this.records.delete(LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash));
+        const key = LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash);
+        const record = this.records.get(key);
+        this.records.delete(key);
+        return record ? LambderMemorySessionStore.storedCopy(record) : null;
     }
     async listSecretHashes(sessionKeyHash) {
         return this.records.values()
             .filter((record) => record.sessionKeyHash === sessionKeyHash)
             .map((record) => record.secretHash);
     }
-    async markDataExpired(sessionKeyHash, secretHash, at) {
-        const record = this.records.get(LambderMemorySessionStore.keyOf(sessionKeyHash, secretHash));
-        if (record)
-            record.dataExpiresAt = at;
-    }
     /** Every live record held, for assertions. */
     list() {
         return this.records.values().map((record) => LambderMemorySessionStore.storedCopy(record));

package/dist/stores/LambderS3FileSource.d.ts

@@ -12,24 +12,39 @@ export type LambderS3FileSourceOptions = {
      * `{ region: "auto", endpoint, credentials }`.
      */
     clientConfig?: S3ClientConfig;
+    /**
+     * The S3 error names that mean "no such file", read as null so the
+     * request falls through. Default: NoSuchKey and NotFound (the key does
+     * not exist), AccessDenied (what S3 answers a reader without
+     * s3:ListBucket for a missing key, since it will not say whether the key
+     * exists), and the refusals of a key S3 will not look up at all:
+     * KeyTooLongError and InvalidURI from S3, InvalidObjectName from R2. A
+     * reader granted s3:ListBucket gets NoSuchKey for a missing key, so a
+     * list without AccessDenied makes a refused credential surface as the
+     * error it is.
+     */
+    notFoundErrorNames?: readonly string[];
 };
 /**
  * Files from an S3 bucket, or any S3-compatible store such as Cloudflare
  * R2 (pass its endpoint in clientConfig). Needs @aws-sdk/client-s3, an
  * optional peer dependency loaded on first read, so apps that serve from a
- * folder never load it. A missing object reads as null and the request
- * falls through; grant s3:ListBucket besides s3:GetObject, otherwise S3
- * answers a missing key with AccessDenied, which propagates as an error.
- * An object's Content-Type is used unless it is a generic octet-stream, in
- * which case the extension decides, as for local files.
+ * folder never load it. A missing object (see `notFoundErrorNames`) reads as
+ * null and the request falls through; any other failure throws. A request
+ * path names the key, so a key that is missing or that S3 refuses to look
+ * up is the visitor's doing, and reading it as an error would answer every
+ * such path with a 500 before an SPA's shell could be served. An object's
+ * Content-Type is used unless it is a generic octet-stream, in which case
+ * the extension decides, as for local files.
  */
 export declare class LambderS3FileSource implements LambderFileSource {
     private readonly bucket;
     private readonly prefix;
     private readonly clientConfig;
+    private readonly notFoundErrorNames;
     private client;
     private sdk;
-    constructor({ bucket, prefix, client, clientConfig }: LambderS3FileSourceOptions);
+    constructor({ bucket, prefix, client, clientConfig, notFoundErrorNames }: LambderS3FileSourceOptions);
     private loadSdk;
     read(relativePath: string): Promise<LambderFile | null>;
 }

package/dist/stores/LambderS3FileSource.js

@@ -1,27 +1,32 @@
 import { remoteStoreFile } from "../shared/contracts/LambderFileSource.js";
+const DEFAULT_NOT_FOUND_ERROR_NAMES = ["NoSuchKey", "NotFound", "AccessDenied", "KeyTooLongError", "InvalidURI", "InvalidObjectName"];
 /**
  * Files from an S3 bucket, or any S3-compatible store such as Cloudflare
  * R2 (pass its endpoint in clientConfig). Needs @aws-sdk/client-s3, an
  * optional peer dependency loaded on first read, so apps that serve from a
- * folder never load it. A missing object reads as null and the request
- * falls through; grant s3:ListBucket besides s3:GetObject, otherwise S3
- * answers a missing key with AccessDenied, which propagates as an error.
- * An object's Content-Type is used unless it is a generic octet-stream, in
- * which case the extension decides, as for local files.
+ * folder never load it. A missing object (see `notFoundErrorNames`) reads as
+ * null and the request falls through; any other failure throws. A request
+ * path names the key, so a key that is missing or that S3 refuses to look
+ * up is the visitor's doing, and reading it as an error would answer every
+ * such path with a 500 before an SPA's shell could be served. An object's
+ * Content-Type is used unless it is a generic octet-stream, in which case
+ * the extension decides, as for local files.
  */
 export class LambderS3FileSource {
     bucket;
     prefix;
     clientConfig;
+    notFoundErrorNames;
     client;
     sdk;
-    constructor({ bucket, prefix = "", client, clientConfig }) {
+    constructor({ bucket, prefix = "", client, clientConfig, notFoundErrorNames = DEFAULT_NOT_FOUND_ERROR_NAMES }) {
         if (!bucket.trim())
             throw new Error("bucket is required");
         this.bucket = bucket;
         this.prefix = prefix;
         this.client = client;
         this.clientConfig = clientConfig;
+        this.notFoundErrorNames = notFoundErrorNames;
     }
     loadSdk() {
         if (!this.sdk) {
@@ -41,7 +46,7 @@ export class LambderS3FileSource {
         }
         catch (err) {
             const name = err.name;
-            if (name === "NoSuchKey" || name === "NotFound")
+            if (typeof name === "string" && this.notFoundErrorNames.includes(name))
                 return null;
             throw err;
         }

package/dist/testing/LambderTestApp.d.ts

@@ -23,9 +23,9 @@ export type LambderTestAppOptions = {
     /**
      * The gateway shape the handler is called with: "v2" (an HTTP API, a
      * Function URL) or "v1" (a REST API). Default: "v2". A handler answers
-     * both alike through its context, so this matters to code that reads the
-     * raw `ctx.event`, and to anyone who wants the suite to run on exactly
-     * what production delivers.
+     * both alike through its context, so this matters only to code that reads
+     * the raw `ctx.event`, or to a suite that should run on exactly what
+     * production delivers.
      */
     eventFormat?: LambderHttpEventFormat;
     /** Default: a fresh LambderMemorySessionStore. Pass your own to run the suite over another store (DynamoDB Local, say). */
@@ -46,8 +46,8 @@ export type LambderTestAppOptions = {
 /**
  * A Lambder instance as a test app takes it: any instance, read for its
  * session data type and, through the ApiContract property rather than the
- * class parameter, for its contract. The property is what lets a large app
- * name its flattened contract interface explicitly
+ * class parameter, for its contract. The property lets a large app name its
+ * flattened contract interface explicitly
  * (`lambderTestApp<SessionData, ApiContractType>(lambder)`) and keep the
  * cheap type check that interface exists for.
  */
@@ -59,17 +59,17 @@ export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionDat
  * stores put under it in place, and as many simulated browsers in front of it
  * as a test needs. No HTTP, no AWS, and nothing in the app restructured.
  *
- * The app's own declarations all run as written: its guards, its named
- * rate-limit policies, its idempotency settings, its session salt, cookie
- * options and dataRefresh, its hooks and error handlers. Only where things
- * rest is replaced, and from the moment this is created the stores the app
- * was configured with are out of the instance's reach, so a test cannot touch
- * a production table even by mistake. What the app reaches on its own (its
- * database, a mailer) is the app's to replace.
+ * The app's own declarations all run as written: guards, named rate-limit
+ * policies, idempotency settings, session salt, cookie options and
+ * dataRefresh, hooks and error handlers. Only where things rest is replaced:
+ * once this is created, the stores the app was configured with are out of the
+ * instance's reach, so a test cannot touch a production table by mistake.
+ * What the app reaches on its own (its database, a mailer) is the app's to
+ * replace.
  *
  * The sibling of LambderMockApp, which serves a contract from mock handlers:
  * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
- * real handlers instead.
+ * real handlers.
  *
  * Time is not this class's: fake `Date` with the test runner
  * (`vi.useFakeTimers({ toFake: ["Date"] })`), which moves the framework, the
@@ -97,22 +97,20 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
     private resetCount;
     private readonly crashList;
     /**
-     * The call a crash happened under. The app answers a crash with a 500
-     * that says nothing about it, so the error has to travel beside the
-     * answer, and with calls running concurrently (a duplicate sent while
-     * the original is in flight is an ordinary idempotency test) only the
-     * async context says which call a crash belongs to.
+     * The call a crash happened under. The app's 500 says nothing about the
+     * crash, so the error travels beside the answer, and with concurrent
+     * calls (a duplicate sent while the original is in flight is an ordinary
+     * idempotency test) only the async context says which call it belongs to.
      */
     private readonly crashScope;
     constructor(lambder: LambderTestedInstance<TSessionData, TContract>, options?: LambderTestAppOptions);
     /**
      * Every error the app threw while answering a request since the last
      * reset, in order: what reached its global error handler, or the
-     * framework's last-resort 500. The answers themselves say nothing about
-     * what was thrown, so this is where a test reads it, and
-     * `expect(app.crashes).toEqual([])` is how one says nothing crashed.
-     * A refusal is not a crash, and neither is an error an `event()` rejects
-     * with, which the test already holds.
+     * framework's last-resort 500. The answers say nothing about what was
+     * thrown, so a test reads it here; `expect(app.crashes).toEqual([])`
+     * says nothing crashed. A refusal is not a crash, and neither is an
+     * error an `event()` rejects with, which the test already holds.
      */
     get crashes(): readonly Error[];
     /** The session manager, for tests that inspect or manipulate sessions directly. Throws when the app has no sessions. */

package/dist/testing/LambderTestApp.js

@@ -12,17 +12,17 @@ import { LambderTestVisitor } from "./LambderTestVisitor.js";
  * stores put under it in place, and as many simulated browsers in front of it
  * as a test needs. No HTTP, no AWS, and nothing in the app restructured.
  *
- * The app's own declarations all run as written: its guards, its named
- * rate-limit policies, its idempotency settings, its session salt, cookie
- * options and dataRefresh, its hooks and error handlers. Only where things
- * rest is replaced, and from the moment this is created the stores the app
- * was configured with are out of the instance's reach, so a test cannot touch
- * a production table even by mistake. What the app reaches on its own (its
- * database, a mailer) is the app's to replace.
+ * The app's own declarations all run as written: guards, named rate-limit
+ * policies, idempotency settings, session salt, cookie options and
+ * dataRefresh, hooks and error handlers. Only where things rest is replaced:
+ * once this is created, the stores the app was configured with are out of the
+ * instance's reach, so a test cannot touch a production table by mistake.
+ * What the app reaches on its own (its database, a mailer) is the app's to
+ * replace.
  *
  * The sibling of LambderMockApp, which serves a contract from mock handlers:
  * the same verbs (`signIn`, `signOut`, `expireSessionData`, `reset`) over the
- * real handlers instead.
+ * real handlers.
  *
  * Time is not this class's: fake `Date` with the test runner
  * (`vi.useFakeTimers({ toFake: ["Date"] })`), which moves the framework, the
@@ -50,16 +50,15 @@ export class LambderTestApp {
     resetCount = 0;
     crashList = [];
     /**
-     * The call a crash happened under. The app answers a crash with a 500
-     * that says nothing about it, so the error has to travel beside the
-     * answer, and with calls running concurrently (a duplicate sent while
-     * the original is in flight is an ordinary idempotency test) only the
-     * async context says which call a crash belongs to.
+     * The call a crash happened under. The app's 500 says nothing about the
+     * crash, so the error travels beside the answer, and with concurrent
+     * calls (a duplicate sent while the original is in flight is an ordinary
+     * idempotency test) only the async context says which call it belongs to.
      */
     crashScope = new AsyncLocalStorage();
     constructor(lambder, options = {}) {
-        // Only a Lambder instance of this same package copy answers to the
-        // key, so the failure is said here rather than as "is not a function".
+        // Only a Lambder instance from this same package copy answers to the
+        // key; saying so here beats a bare "is not a function".
         if (typeof lambder?.[LAMBDER_BACKEND_SWAP] !== "function") {
             throw new Error("lambderTestApp: expected a Lambder instance (what initLambder().create() returns), from the same installed copy of lambder as lambder/testing.");
         }
@@ -94,11 +93,11 @@ export class LambderTestApp {
                 return { result: await this.crashScope.run(scope, run), crash: scope.crash };
             },
             issueSession: async (host, sessionKey, data, ttlSeconds) => {
-                // Through a session controller on a request context, the way a
-                // login handler does it, so the cookies are the ones the app's
-                // own cookie options produce for that host.
+                // Through a session controller on a request context, as a
+                // login handler does, so the cookies are what the app's own
+                // cookie options produce for that host.
                 const event = synthesizeLambdaHttpEvent({ method: "GET", path: "/", host }, { invoke: false });
-                const ctx = createContext(event, localLambdaContext("lambder-test"), lambder.apiPath);
+                const ctx = createContext(event, localLambdaContext("lambder-test"), { apiPath: lambder.apiPath });
                 const created = await lambder.getSessionController(ctx).issueSession(sessionKey, data, ttlSeconds);
                 const headers = {};
                 ctx.responseHeaders.applyInto(headers);
@@ -109,11 +108,10 @@ export class LambderTestApp {
     /**
      * Every error the app threw while answering a request since the last
      * reset, in order: what reached its global error handler, or the
-     * framework's last-resort 500. The answers themselves say nothing about
-     * what was thrown, so this is where a test reads it, and
-     * `expect(app.crashes).toEqual([])` is how one says nothing crashed.
-     * A refusal is not a crash, and neither is an error an `event()` rejects
-     * with, which the test already holds.
+     * framework's last-resort 500. The answers say nothing about what was
+     * thrown, so a test reads it here; `expect(app.crashes).toEqual([])`
+     * says nothing crashed. A refusal is not a crash, and neither is an
+     * error an `event()` rejects with, which the test already holds.
      */
     get crashes() {
         return this.crashList;