lambder 7.2.5 → 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

@@ -0,0 +1,176 @@
+import type { Context } from "aws-lambda";
+import type Lambder from "../core/Lambder.js";
+import { type LambderHttpEventFormat } from "../core/LambderContext.js";
+import type { LambderHandler } from "../core/LambderCreateOptions.js";
+import type LambderSessionManager from "../session/LambderSessionManager.js";
+import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js";
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import { LambderTestVisitor, type LambderTestVisitorArgs, type LambderTestVisitorOptions } from "./LambderTestVisitor.js";
+/**
+ * What a test app may be told. Nothing is required: `lambderTestApp(lambder)`
+ * is a working test app over memory stores.
+ *
+ * The stores sit where create() takes them (`session.store`,
+ * `rateLimits.limiter`, `idempotency.store`, `files`), naming only the part a
+ * test replaces; everything else the app configured there stays in force.
+ */
+export type LambderTestAppOptions = {
+    /** The host visitors browse unless they name their own. Default: "localhost". An app that scopes its session cookie to a domain needs a host under it. */
+    host?: string;
+    /**
+     * 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 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). */
+    session?: {
+        store?: LambderSessionStore<any>;
+    };
+    /** Default: a fresh LambderMemoryRateLimiter. */
+    rateLimits?: {
+        limiter?: LambderRateLimiter;
+    };
+    /** Default: a fresh LambderMemoryIdempotencyStore. */
+    idempotency?: {
+        store?: LambderIdempotencyStore;
+    };
+    /** Default: the app's own source, which suits one that reads a local folder. Pass a LambderLocalFileSource over fixtures for an app whose production source is S3 or HTTP. */
+    files?: LambderFileSource;
+};
+/**
+ * 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 lets a large app name its
+ * flattened contract interface explicitly
+ * (`lambderTestApp<SessionData, ApiContractType>(lambder)`) and keep the
+ * cheap type check that interface exists for.
+ */
+export type LambderTestedInstance<TSessionData, TContract> = Lambder<TSessionData, any, any, any, any, any, any, any> & {
+    readonly ApiContract: TContract;
+};
+/**
+ * A real Lambder app under test: the instance an app already has, with memory
+ * 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: 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.
+ *
+ * Time is not this class's: fake `Date` with the test runner
+ * (`vi.useFakeTimers({ toFake: ["Date"] })`), which moves the framework, the
+ * memory stores and the app's own handlers together.
+ *
+ * One test app per instance: a second one puts its own stores under the same
+ * instance and takes over its crash watch, so the first stops seeing either.
+ */
+export declare class LambderTestApp<TContract extends LambderApiContractShape = any, TSessionData = any> {
+    /** The instance's handler: what `event()` and every visitor call. */
+    readonly handler: LambderHandler;
+    /** The host visitors browse unless they name their own. */
+    readonly host: string;
+    /** The session store now under the instance, for assertions; null when the app has no sessions. A LambderMemorySessionStore unless one was given. */
+    readonly sessionStore: LambderSessionStore<TSessionData> | null;
+    /** The rate limiter now under the instance; null when the app declares no rate limits. */
+    readonly rateLimiter: LambderRateLimiter | null;
+    /** The idempotency store now under the instance; null when the app has no idempotency. */
+    readonly idempotencyStore: LambderIdempotencyStore | null;
+    private readonly lambder;
+    private readonly wiring;
+    /** The memory stores this test app made itself, which reset() empties. One the test supplied is the test's: nothing here knows what else holds it. */
+    private readonly ownStores;
+    private visitorCount;
+    private resetCount;
+    private readonly crashList;
+    /**
+     * 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 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. */
+    get sessionManager(): LambderSessionManager<TSessionData>;
+    /**
+     * A new simulated browser: its own cookie jar, and its own address unless
+     * one is given. A stranger until it signs in, through the app's own login
+     * API or through `signIn`.
+     */
+    visitor<TProvidedGuards extends string = never>(...[options]: LambderTestVisitorArgs<LambderTestVisitorOptions<TContract, TProvidedGuards>, TProvidedGuards>): LambderTestVisitor<TContract, TSessionData, TProvidedGuards>;
+    /**
+     * A new visitor, already signed in: `visitor()` followed by its
+     * `signIn()`. The session is minted by the app's own session model, so
+     * no login endpoint has to exist or be called.
+     *
+     * ```typescript
+     * const admin = await app.signIn("user:ada", { userId: "ada", role: "admin" });
+     * expect(await admin.api("org.rename", { name })).toEqual({ ok: true });
+     * ```
+     */
+    signIn<TProvidedGuards extends string = never>(sessionKey: string, data: TSessionData, ...[options]: LambderTestVisitorArgs<LambderTestVisitorOptions<TContract, TProvidedGuards> & {
+        ttlSeconds?: number;
+    }, TProvidedGuards>): Promise<LambderTestVisitor<TContract, TSessionData, TProvidedGuards>>;
+    /**
+     * Ends every session of the subject, the way "log out everywhere" does.
+     * A visitor signed in as that subject keeps its cookies, as a browser
+     * would, so its next call is what a real one's would be: answered
+     * sessionExpired, with the stale cookies evicted.
+     */
+    signOut(sessionKey: string): Promise<void>;
+    /** Marks the subject's session data stale, so the next read renews it through the app's dataRefresh. */
+    expireSessionData(sessionKey: string): Promise<void>;
+    /**
+     * Hands the handler an event that is not an HTTP request (a schedule, an
+     * SNS or SQS delivery), which is how an addAction handler runs, with a
+     * Lambda context filled in. Resolves to whatever the action returned.
+     *
+     * ```typescript
+     * await app.event({ source: "aws.events", "detail-type": "Scheduled Event" });
+     * ```
+     */
+    event(event: unknown, context?: Partial<Context>): Promise<unknown>;
+    /**
+     * Rewinds what accumulated: sessions, rate-limit counters and replay
+     * records in the stores this test app made, the crashes it recorded, and
+     * the cookies of every visitor it created (each empties its jar the next
+     * time it is used). For a beforeEach. The app's own data (its database)
+     * is the app's to rewind.
+     */
+    reset(): void;
+}
+/**
+ * Puts a built Lambder instance under test. See LambderTestApp.
+ *
+ * ```typescript
+ * import { lambderTestApp } from "lambder/testing";
+ * import { lambder } from "../src/index.js";
+ *
+ * const app = lambderTestApp(lambder);
+ * beforeEach(() => app.reset());
+ * ```
+ */
+export declare const lambderTestApp: <TSessionData = any, TContract extends LambderApiContractShape = any>(lambder: LambderTestedInstance<TSessionData, TContract>, options?: LambderTestAppOptions) => LambderTestApp<TContract, TSessionData>;