lambder 10.1.1 → 11.0.1

package/CHANGELOG.md

@@ -9,6 +9,87 @@ 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.
 
+## [11.0.1] - 2026-09-29
+
+A major for an app with many APIs: what one API costs the type checker no
+longer grows with the app's keyed guards and rate-limit policies. The same
+declarations compile and the same ones fail, and nothing changes at runtime.
+It is a major because the exported option types no longer take the API's
+input.
+
+### Changed (breaking)
+
+- **`LambderGuardsOption`, `LambderRateLimitOption`, `LambderAllowedGuardNames`,
+  `LambderParamlessGuardNames` and `LambderAllowedPolicyNames` no longer take
+  a payload.** They name what an instance lets one kind of API declare
+  (session guards and session-keyed policies only on session APIs) and depend
+  on the instance alone. Whether an API's input carries the fields an apiInput
+  guard or an apiInput-keyed policy reads is asked separately, of the names
+  the API declared, by `LambderGuardNamesInputLacks` and
+  `LambderPolicyNamesInputLacks`.
+  - To move: drop the payload argument (`LambderGuardsOption<Guards, true>`
+    for `LambderGuardsOption<Guards, Payload, true>`), and where you relied on
+    the payload filter, ask the new types of the names you declared.
+
+### Changed
+
+- **An API's `guards` and `rateLimit` options are held to its input once the
+  input is known.** Their constraints used to read the API's own input type,
+  so for every API the compiler rebuilt the names it may declare, over every
+  guard and policy the instance holds, while that input was still being
+  inferred. The work grew with an app's APIs times its apiInput guards and
+  apiInput-keyed policies, exponentially in the worst case: 25 APIs
+  registered in one chain, each declaring one of 10 apiInput guards, took
+  12.6 million type instantiations. The constraints now depend on the
+  instance alone, and `LambderPayloadSliceCheck`, intersected onto the
+  options, refuses an apiInput guard or policy whose fields the input does
+  not carry. The same 25 APIs now take 45 thousand, about what they cost on
+  guards that read no input.
+- **Where the error shows.** A guard or policy the input cannot carry is
+  refused on the `guards` or `rateLimit` value rather than on the name inside
+  it, and the message names the guards or policies at fault ("lambder: these
+  guards read fields this API's input does not carry"). Completion inside
+  those options offers every declared name.
+
+### Added
+
+- **`LambderGuardNamesInputLacks` and `LambderPolicyNamesInputLacks`**: the
+  apiInput guards, and the apiInput-keyed policies, among some names whose
+  fields an input does not carry. The input is compared whole, so a union
+  input carries a slice only when every member does.
+- **A type-cost test** (`tests/api/api-policy-type-cost.test.ts`): forty APIs
+  compiled on an instance whose ten guards and ten policies read the input,
+  and on one whose same-named ones do not, must cost about the same.
+
+## [10.2.1] - 2026-09-29
+
+A minor for an app that keeps its cache in its own storage. It writes a few
+small storage methods and gets a `LambderCache` that keeps the same rules as
+the DynamoDB cache and its memory twin, rather than rewriting those rules and
+drifting from them. Nothing existing changes.
+
+### Added
+
+- **`LambderStorageBackedCache`: a `LambderCache` over storage the app
+  supplies.** `new LambderStorageBackedCache({ storage, defaultTtlSeconds?,
+  maxValueBytes?, now? })` takes a `LambderCacheStorage`, five methods over
+  the app's own table (`read`, `write`, `delete`, `deletePartition`,
+  `listSortKeys`), and brings every rule itself: the same key checks, the
+  value stored as its JSON text and handed back as a fresh parse, the same
+  TTL and expiry second, only live entries counted by `delete` and
+  `deletePartition`, sort keys listed in the table's order whatever order the
+  storage finds them in, and `getOrSet`'s single-flight in one process, its
+  fail-open when the storage throws, and a `set`, `delete` or
+  `deletePartition` of a key winning over a fill in progress. The conformance
+  suite that drives `LambderDdbCache` and `LambderMemoryCache` drives it too.
+  It holds no fill lease across processes and no memory layer. The storage
+  receives a checked `LambderCacheAddress` (`partition`, `sortKey`, null for a
+  plain key, and `memoryKey`) and stores a `LambderCacheStoredEntry` (`json`,
+  `expiresAt` in epoch seconds). Exported with
+  `LambderStorageBackedCacheOptions`, `LambderCacheStorage`,
+  `LambderCacheStoredEntry` and `LambderCacheAddress`; docs/ddb-cache.md
+  shows a storage over a SQL table.
+
 ## [10.1.1] - 2026-09-28
 
 A minor for an app made of parts. Each part can declare its own guards and

package/README.md

@@ -191,7 +191,7 @@ framework:
 | --- | --- | --- |
 | `html` / `xml` tags + `LambderTemplatingEngine` | [Templating](./docs/templating.md) | Type-safe tagged templates and a comment-only HTML template engine (build-pipeline-safe) |
 | `createLambderI18n` | [Translations](./docs/i18n.md) | Typed translations with enforced/optional languages, component-level extension, auto language detection and on-demand language loading (isomorphic) |
-| `LambderDdbCache` / `LambderMemoryCache` | [DynamoDB cache](./docs/ddb-cache.md) | JSON cache behind one `LambderCache` interface: DynamoDB-backed and compressed, with lease-based single-fill and grouped keys (server-only), or in memory for tests |
+| `LambderDdbCache` / `LambderMemoryCache` / `LambderStorageBackedCache` | [DynamoDB cache](./docs/ddb-cache.md) | JSON cache behind one `LambderCache` interface: DynamoDB-backed and compressed, with lease-based single-fill and grouped keys (server-only), in memory for tests, or over an app's own storage (a SQL table, Redis) with the same rules |
 | `LambderDdbRateLimiter` / `LambderMemoryRateLimiter` | [Rate limiter](./docs/ddb-rate-limiter.md) | Fixed-window rate limiter, atomic per window, in DynamoDB (server-only) or in memory |
 | `LambderDdbIdempotencyStore` / `LambderMemoryIdempotencyStore` | [Idempotency store](./docs/ddb-idempotency.md) | Idempotency records with owner-checked claims, in DynamoDB (compressed replays, server-only) or in memory |
 | `LambderMockApp` | [The mock runtime](./docs/mock.md) | The typed contract served from mock handlers over the real API pipeline, with failure injection, sessions and a call log (isomorphic) |

package/dist/api/LambderApiGuards.d.ts

@@ -272,33 +272,40 @@ export type LambderGuardMetaMap<TGuards> = {
     [K in keyof TGuards]: LambderGuardMeta<TGuards[K]>;
 };
 /**
- * The guard name when the API's payload carries the guard's apiInput slice.
- * The payload is compared whole, not member by member: a bare `TPayload
- * extends R` would distribute over a union input, so a slice one member
- * carries would be allowed on an API whose other members lack it, and every
- * request of those members would be refused by the slice's parse.
+ * Guard names an API may declare: every guard the instance holds, session
+ * guards only on session APIs. Whether the API's input carries the fields an
+ * apiInput guard reads is asked of the names it declared, once that input is
+ * known, by LambderGuardNamesInputLacks.
  */
-type LambderGuardNameIfPayloadOk<TGuards, K extends keyof TGuards, TPayload> = TGuards[K] extends {
-    apiInput: infer R;
-} ? ([TPayload] extends [R] ? K : never) : K;
-/**
- * Guard names an API may declare: apiInput-mode guards only when the API's
- * payload carries their fields, session guards only on session APIs.
- */
-export type LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession extends boolean = true> = {
+export type LambderAllowedGuardNames<TGuards, TIncludeSession extends boolean = true> = {
     [K in keyof TGuards]: TGuards[K] extends {
         session: true;
-    } ? (TIncludeSession extends true ? LambderGuardNameIfPayloadOk<TGuards, K, TPayload> : never) : LambderGuardNameIfPayloadOk<TGuards, K, TPayload>;
+    } ? (TIncludeSession extends true ? K : never) : K;
 }[keyof TGuards] & string;
+/**
+ * The apiInput guards among `TNames` whose fields the API's payload does not
+ * carry. addApi and addSessionApi ask this once the API's input is known, of
+ * the names its guards option holds; see LambderPayloadSliceCheck.
+ *
+ * The payload is compared whole, not member by member: a bare `TPayload
+ * extends R` would distribute over a union input, so a slice one member
+ * carries would pass on an API whose other members lack it, and every
+ * request of those members would be refused by the slice's parse.
+ */
+export type LambderGuardNamesInputLacks<TGuards, TNames, TPayload> = {
+    [K in TNames & keyof TGuards]: TGuards[K] extends {
+        apiInput: infer R;
+    } ? ([TPayload] extends [R] ? never : K) : never;
+}[TNames & keyof TGuards] & string;
 /** The allowed guard names whose handler takes no param (usable in the string/array forms). */
-export type LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession extends boolean> = {
-    [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
+export type LambderParamlessGuardNames<TGuards, TIncludeSession extends boolean> = {
+    [K in LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards]: TGuards[K] extends {
         param: undefined;
     } ? K & string : never;
-}[LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards];
+}[LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards];
 /** The map form's full shape: every declarable guard name, each carrying its own param type. */
-type LambderGuardsMap<TGuards, TPayload, TIncludeSession extends boolean> = {
-    readonly [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
+type LambderGuardsMap<TGuards, TIncludeSession extends boolean> = {
+    readonly [K in LambderAllowedGuardNames<TGuards, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
         param: undefined;
     } ? true : TGuards[K] extends {
         param: infer P;
@@ -312,11 +319,15 @@ type LambderGuardsMap<TGuards, TPayload, TIncludeSession extends boolean> = {
  *
  * Every form is non-empty by construction, so declaring the option is always
  * declaring a guard. See LambderNonEmptyOptionMap.
+ *
+ * It depends on the instance alone, never on the API's input, so the
+ * compiler builds it once per instance rather than once per API; see
+ * LambderPayloadSliceCheck for why, and for where the input is asked.
  */
-export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly [
-    LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>,
-    ...LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[]
-] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards, TPayload, TIncludeSession>>;
+export type LambderGuardsOption<TGuards, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TIncludeSession> | readonly [
+    LambderParamlessGuardNames<TGuards, TIncludeSession>,
+    ...LambderParamlessGuardNames<TGuards, TIncludeSession>[]
+] | LambderNonEmptyOptionMap<LambderGuardsMap<TGuards, TIncludeSession>>;
 /**
  * The typed ctx.guardData an API's handler sees: declared guards that return
  * a value, keyed by name. Check-only (void) guards never appear.

package/dist/api/LambderApiRateLimits.d.ts

@@ -147,22 +147,35 @@ export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderA
 type LambderPolicyPerOf<TPolicy> = "per" extends keyof TPolicy ? TPolicy["per" & keyof TPolicy] : undefined;
 /**
  * Policy names an API may reference: session-keyed policies only on session
- * APIs, apiInput-keyed policies only when the API's payload carries the
- * key's fields, and never a policy without `per`, whose key only the code
- * that charges it knows. A policy whose type does not settle its `per` is
- * allowed here and checked at registration.
- *
- * The payload is compared whole, as the guards' check does it: a union input
- * one of whose members lacks the key's fields does not carry them, and every
- * request of that member would be refused by the key slice's parse.
+ * APIs, and never a policy without `per`, whose key only the code that
+ * charges it knows. A policy whose type does not settle its `per` is allowed
+ * here and checked at registration. Whether the API's input carries the
+ * fields an apiInput-keyed policy reads is asked of the names it declared,
+ * once that input is known, by LambderPolicyNamesInputLacks.
  */
-export type LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession extends boolean> = {
+export type LambderAllowedPolicyNames<TPolicies, TIncludeSession extends boolean> = {
     [K in keyof TPolicies]: [
         LambderPolicyPerOf<TPolicies[K]>
-    ] extends [undefined] ? never : [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? (TIncludeSession extends true ? K : never) : [LambderPolicyPerOf<TPolicies[K]>] extends [{
-        apiInput: infer S extends z.ZodType;
-    }] ? ([TPayload] extends [z.input<S>] ? K : never) : K;
+    ] extends [undefined] ? never : [LambderPolicyPerOf<TPolicies[K]>] extends ["session"] ? (TIncludeSession extends true ? K : never) : K;
 }[keyof TPolicies] & string;
+/**
+ * The apiInput-keyed policies among `TNames` whose key fields the API's
+ * payload does not carry. addApi and addSessionApi ask this once the API's
+ * input is known, of the names its rateLimit option holds; see
+ * LambderPayloadSliceCheck.
+ *
+ * The payload is compared whole, as LambderGuardNamesInputLacks compares it:
+ * a union input one of whose members lacks the key's fields does not carry
+ * them, and every request of that member would be refused by the key
+ * slice's parse.
+ */
+export type LambderPolicyNamesInputLacks<TPolicies, TNames, TPayload> = {
+    [K in TNames & keyof TPolicies]: [
+        LambderPolicyPerOf<TPolicies[K]>
+    ] extends [{
+        apiInput: infer S extends z.ZodType;
+    }] ? ([TPayload] extends [z.input<S>] ? never : K) : never;
+}[TNames & keyof TPolicies] & string;
 /**
  * Policy names a handler may charge itself: every policy except one keyed by
  * a `{ apiInput?, handler }` key, which derives its key from an API's payload
@@ -222,8 +235,8 @@ type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
     budget: "perPolicy";
 } ? Pick<LambderRateLimitOverride, "refusal"> : LambderRateLimitOverride;
 /** The map form's full shape: every referable policy name, each carrying its own override. */
-type LambderRateLimitMap<TPolicies, TPayload, TIncludeSession extends boolean> = {
-    readonly [K in LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
+type LambderRateLimitMap<TPolicies, TIncludeSession extends boolean> = {
+    readonly [K in LambderAllowedPolicyNames<TPolicies, TIncludeSession> & keyof TPolicies]?: true | LambderRateLimitOverrideFor<TPolicies[K]>;
 };
 /**
  * The per-API `rateLimit` option: one policy name, a non-empty ordered list
@@ -234,11 +247,14 @@ type LambderRateLimitMap<TPolicies, TPayload, TIncludeSession extends boolean> =
  * Every form is non-empty by construction (LambderNonEmptyOptionMap, as the
  * guards option uses), since `rateLimit: {}`, `rateLimit: []` and
  * `rateLimit: { policy: undefined }` would announce a limit and enforce none.
+ *
+ * It depends on the instance alone, never on the API's input, as
+ * LambderGuardsOption does; see LambderPayloadSliceCheck.
  */
-export type LambderRateLimitOption<TPolicies, TPayload, TIncludeSession extends boolean> = LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession> | readonly [
-    LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession>,
-    ...LambderAllowedPolicyNames<TPolicies, TPayload, TIncludeSession>[]
-] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies, TPayload, TIncludeSession>>;
+export type LambderRateLimitOption<TPolicies, TIncludeSession extends boolean> = LambderAllowedPolicyNames<TPolicies, TIncludeSession> | readonly [
+    LambderAllowedPolicyNames<TPolicies, TIncludeSession>,
+    ...LambderAllowedPolicyNames<TPolicies, TIncludeSession>[]
+] | LambderNonEmptyOptionMap<LambderRateLimitMap<TPolicies, TIncludeSession>>;
 /**
  * When in a call a policy is checked.
  *

package/dist/core/Lambder.d.ts

@@ -24,7 +24,7 @@ import type { LambderApiIdempotencyConfig } from "../api/LambderApiIdempotency.j
 import type { LambderContractEntry, LambderJsonOf, LambderMergeContract } from "../shared/wire/LambderApiContract.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
 import type { LambderReadonlyDeep, MaybePromise } from "../shared/util/LambderTypeUtilities.js";
-import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderRouteHandler, type LambderInputValidationHandler, type LambderFallbackHandler, type LambderGlobalErrorHandler, type LambderAfterRenderHook, type LambderBeforeRenderHook, type LambderFallbackHook, type LambderActionTools, type LambderCreateOptions, type LambderGivenOption, type LambderHandler, type LambderNestedOptionChecks, type LambderObjectOutputCheck, type LambderRequirableGuardsField, type LambderSessionEnabledInstance, type LambderSessionRouteHandler } from "./LambderCreateOptions.js";
+import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderRouteHandler, type LambderInputValidationHandler, type LambderFallbackHandler, type LambderGlobalErrorHandler, type LambderAfterRenderHook, type LambderBeforeRenderHook, type LambderFallbackHook, type LambderActionTools, type LambderCreateOptions, type LambderGivenOption, type LambderHandler, type LambderNestedOptionChecks, type LambderObjectOutputCheck, type LambderPayloadSliceCheck, type LambderRequirableGuardsField, type LambderSessionEnabledInstance, type LambderSessionRouteHandler } from "./LambderCreateOptions.js";
 /** Everything `lambder/testing` may put under a built instance: the pipeline's stores, and the source its files are read from. */
 export type LambderInstanceBackends = LambderPipelineBackends & {
     fileSource?: LambderFileSource;
@@ -167,7 +167,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addRoute(condition: RegExp | LambderRouteConditionFn | LambderRouteMatcher, actionFn: LambderRouteHandler): this;
     addSessionRoute<TPath extends LambderRoutePath>(condition: TPath, actionFn: ((ctx: LambderSessionRenderContext<any, TSessionData, LambderPathParamsOf<TPath>, {}, _TRateLimitPolicies>, resolver: LambderResolver) => MaybePromise<LambderResponse>) & LambderSessionEnabledInstance<_TSessionsEnabled>): this;
     addSessionRoute(condition: RegExp | LambderRouteConditionFn | LambderRouteMatcher, actionFn: LambderSessionRouteHandler<TSessionData> & LambderSessionEnabledInstance<_TSessionsEnabled>): this;
-    addApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.input<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.input<TInput>, false> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never, const TRefusalsOpt extends LambderRefusalsOption<_TRefusals> = never>(name: TName, schema: {
+    addApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, false> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never, const TRefusalsOpt extends LambderRefusalsOption<_TRefusals> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
@@ -189,12 +189,12 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
          * both ends. A transport setting of this server's, not part of the API's contract.
          */
         compress?: boolean | "auto";
-    } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt> & LambderObjectOutputCheck<TOutput>, 
+    } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt> & LambderObjectOutputCheck<TOutput> & LambderPayloadSliceCheck<_TGuards, _TRateLimitPolicies, TGuardsOpt, TRateOpt, z.input<TInput>>, 
     /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
     handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>, TSessionData, _TRateLimitPolicies> & {
         refuse: LambderDeclaredRefuse<LambderHandlerRefusalsOf<_TRefusals, LambderApiRefusalCodes<_TRefusals, _TGuards, TRefusalsOpt, TGuardsOpt>>, _TRefusalCodesRequired>;
     }) => MaybePromise<TAnswer>): Lambder<TSessionData, LambderMergeContract<_TContract, TName, LambderContractEntry<z.input<TInput>, LambderJsonOf<z.output<TOutput>>, "public", LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt, TRateOpt, TIdempotencyOpt, LambderWireRefusalsOf<_TRefusals, LambderApiRefusalCodes<_TRefusals, _TGuards, TRefusalsOpt, TGuardsOpt>>>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired, _TSessionsEnabled, _TRefusals, _TRefusalCodesRequired>;
-    addSessionApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.input<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.input<TInput>, true> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never, const TRefusalsOpt extends LambderRefusalsOption<_TRefusals> = never>(name: TName, schema: {
+    addSessionApi<TName extends string, TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, true> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never, const TRefusalsOpt extends LambderRefusalsOption<_TRefusals> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
@@ -216,7 +216,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
          * both ends. A transport setting of this server's, not part of the API's contract.
          */
         compress?: boolean | "auto";
-    } & LambderRequirableGuardsField<_TSessionGuardsRequired, TGuardsOpt> & LambderSessionEnabledInstance<_TSessionsEnabled> & LambderObjectOutputCheck<TOutput>, 
+    } & LambderRequirableGuardsField<_TSessionGuardsRequired, TGuardsOpt> & LambderSessionEnabledInstance<_TSessionsEnabled> & LambderObjectOutputCheck<TOutput> & LambderPayloadSliceCheck<_TGuards, _TRateLimitPolicies, TGuardsOpt, TRateOpt, z.input<TInput>>, 
     /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
     handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>, _TRateLimitPolicies> & {
         refuse: LambderDeclaredRefuse<LambderHandlerRefusalsOf<_TRefusals, LambderApiRefusalCodes<_TRefusals, _TGuards, TRefusalsOpt, TGuardsOpt>>, _TRefusalCodesRequired>;

package/dist/core/LambderCreateOptions.d.ts

@@ -11,12 +11,12 @@ import type { LambderSessionDataRefreshConfig } from "../session/LambderSessionM
 import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
 import type { LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import type { LambderSessionCrypto } from "../session/LambderSessionCrypto.js";
-import type { LambderApiGuard } from "../api/LambderApiGuards.js";
-import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig } from "../api/LambderApiRateLimits.js";
+import type { LambderApiGuard, LambderGuardNamesInputLacks } from "../api/LambderApiGuards.js";
+import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderPolicyNamesInputLacks } from "../api/LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "../api/LambderApiIdempotency.js";
 import { type LambderRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
-import type { LambderJsonOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderGuardNamesIn, LambderJsonOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderRateLimitMessage } from "../shared/wire/LambderApiOptionValues.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
 export type LambderRouteHandler = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
@@ -385,6 +385,31 @@ type LambderObjectOutputRefusal = {
         readonly "lambder: an API answers with an object or an array. One with nothing to answer declares output: z.object({}) and returns {}.": never;
     };
 };
+/**
+ * An API's guards and rate limits held to its input once the input is known.
+ * Intersected onto an API's options: a guard or a policy that reads fields
+ * the input does not carry is refused on the option that names it, the
+ * property name is the message and its value the names at fault.
+ *
+ * The options' own constraints admit every name the instance declares, and
+ * the input is asked about here instead, on purpose. A constraint that reads
+ * the API's input is rebuilt for every API while that input is still being
+ * inferred, over every name the instance declares, so the compiler's work
+ * grows with an app's APIs times its keyed guards and policies, exponentially
+ * in the worst case. Here the question is asked once per API, of the names
+ * that API declared.
+ */
+export type LambderPayloadSliceCheck<TGuards, TPolicies, TGuardsOpt, TRateOpt, TPayload> = LambderGuardsSliceCheck<LambderGuardNamesInputLacks<TGuards, LambderGuardNamesIn<TGuardsOpt>, TPayload>> & LambderRateLimitSliceCheck<LambderPolicyNamesInputLacks<TPolicies, LambderGuardNamesIn<TRateOpt>, TPayload>>;
+type LambderGuardsSliceCheck<TLacking> = [TLacking] extends [never] ? unknown : {
+    guards: {
+        readonly "lambder: these guards read fields this API's input does not carry": TLacking;
+    };
+};
+type LambderRateLimitSliceCheck<TLacking> = [TLacking] extends [never] ? unknown : {
+    rateLimit: {
+        readonly "lambder: these rate limits are keyed by fields this API's input does not carry": TLacking;
+    };
+};
 /**
  * The `guards` field of an API's options: optional by default, required once
  * create() received the require*ApiGuards flag for that kind of API, so that

package/dist/index.d.ts

@@ -108,6 +108,9 @@ export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
 export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
 export type { LambderMemoryCacheOptions } from "./stores/LambderMemoryCache.js";
+export { LambderStorageBackedCache } from "./stores/LambderStorageBackedCache.js";
+export type { LambderStorageBackedCacheOptions, LambderCacheStorage, LambderCacheStoredEntry, } from "./stores/LambderStorageBackedCache.js";
+export type { LambderCacheAddress } from "./stores/LambderCacheKeys.js";
 export { RATE_LIMIT_WINDOWS } from "./shared/contracts/LambderRateLimiter.js";
 export type { LambderRateLimiter, LambderRateLimitWindow, LambderRateLimitPolicy, LambderRateLimitExceeded, LambderRateLimitResult, } from "./shared/contracts/LambderRateLimiter.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
@@ -125,12 +128,12 @@ export type { LambderDdbIdempotencyStoreOptions } from "./stores/LambderDdbIdemp
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
 export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.js";
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
-export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusals, LambderGuardRefusalNamesOf, } from "./api/LambderApiGuards.js";
+export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderGuardNamesInputLacks, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusals, LambderGuardRefusalNamesOf, } from "./api/LambderApiGuards.js";
 export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
 export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
-export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
+export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderPolicyNamesInputLacks, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
 export type { LambderGuardsOptionValue, LambderRateLimitMessage, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderRefusalsOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";

package/dist/index.js

@@ -74,6 +74,7 @@ export { LambderSessionDataRefreshError, LambderSessionReadError } from "./sessi
 export { LambderSessionNotFoundError, LambderSessionAmbiguousError } from "./session/LambderSessionController.js";
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
+export { LambderStorageBackedCache } from "./stores/LambderStorageBackedCache.js";
 // Fixed-window rate limiting: the shared vocabulary, the DynamoDB limiter and the in-memory one
 export { RATE_LIMIT_WINDOWS } from "./shared/contracts/LambderRateLimiter.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";

package/dist/shared/contracts/LambderCache.d.ts

@@ -29,10 +29,11 @@ export interface LambderCacheListOptions {
     limit?: number;
 }
 /**
- * What an app asks of a cache. LambderDdbCache and LambderMemoryCache
- * implement it with the same rules (the same key limits, the same JSON round
- * trip, the same expiry), so code written against this interface behaves the
- * same over either.
+ * What an app asks of a cache. LambderDdbCache, LambderMemoryCache and
+ * LambderStorageBackedCache (over an app's own storage) implement it with the
+ * same rules (the same key limits, the same JSON round trip, the same
+ * expiry), so code written against this interface behaves the same over any
+ * of them.
  *
  * Values are JSON: what `set` is handed is stored as its JSON text and `get`
  * hands back a parse of it, never the object that was stored.

package/dist/stores/LambderCacheFiller.d.ts

@@ -26,8 +26,9 @@ export type LambderCacheLoad<T> = (store: (value: T) => Promise<T>) => Promise<T
  * write starts a load of its own instead of joining the old one. The old
  * fill's callers get its value uncached.
  *
- * LambderDdbCache and LambderMemoryCache each supply only their read-then-fill
- * and hold one filler, so the two cannot drift on any of the above.
+ * LambderDdbCache, LambderMemoryCache and LambderStorageBackedCache each
+ * supply only their read-then-fill and hold one filler, so they cannot drift
+ * on any of the above.
  */
 export declare class LambderCacheFiller {
     private readonly inFlight;

package/dist/stores/LambderCacheFiller.js

@@ -20,8 +20,9 @@ import { asStoredJson } from "./LambderCacheValues.js";
  * write starts a load of its own instead of joining the old one. The old
  * fill's callers get its value uncached.
  *
- * LambderDdbCache and LambderMemoryCache each supply only their read-then-fill
- * and hold one filler, so the two cannot drift on any of the above.
+ * LambderDdbCache, LambderMemoryCache and LambderStorageBackedCache each
+ * supply only their read-then-fill and hold one filler, so they cannot drift
+ * on any of the above.
  */
 export class LambderCacheFiller {
     inFlight = new Map();

package/dist/stores/LambderCacheKeys.d.ts

@@ -1,9 +1,13 @@
 import type { LambderCacheKey } from "../shared/contracts/LambderCache.js";
-/** One entry's address, normalized: `sortKey` is null for a plain string key. */
+/**
+ * One entry's address, normalized: `sortKey` is null for a plain string key.
+ * A sort key is never empty (a blank one is refused), so a storage whose
+ * column cannot hold null can keep a plain key's entry under "".
+ */
 export interface LambderCacheAddress {
     partition: string;
     sortKey: string | null;
-    /** Unambiguous key for an in-memory layer and an in-flight map. */
+    /** One string that tells every address apart: the key of an in-memory layer, an in-flight map, or a storage keyed by one string. */
     memoryKey: string;
 }
 /**
@@ -13,11 +17,18 @@ export interface LambderCacheAddress {
  * `<encoded>#` an unambiguous boundary for prefix queries. Escaping is
  * per-character, so a prefix of the raw key stays a prefix of the encoded
  * one; only the sort ORDER of keys that contain `#` or `~` shifts, since both
- * encode into the `~` range. The memory cache sorts by the same encoding, so
- * listSortKeys answers in the same order over either store.
+ * encode into the `~` range. The other caches sort by the same encoding (see
+ * compareCacheSortKeys), so listSortKeys answers in the same order over any.
  */
 export declare const encodeCacheSortKey: (value: string) => string;
 export declare const decodeCacheSortKey: (value: string) => string;
+/**
+ * Orders two sort keys as LambderDdbCache lists them, for the caches that
+ * sort a listing themselves: by the whole item sort key the table ranges
+ * over, which carries a "#" after the encoded key. So "New York City" sorts
+ * before "New York" (" " is below "#"), over every cache alike.
+ */
+export declare const compareCacheSortKeys: (first: string, second: string) => number;
 /** Length-prefixed so a partition ending in the separator cannot collide with a sort key. */
 export declare const cacheMemoryKeyOf: (partition: string, sortKey: string | null) => string;
 /** A partition as the caches accept it, or a throw naming what is wrong with it. */

package/dist/stores/LambderCacheKeys.js

@@ -1,10 +1,11 @@
 /*
- * How a cache key is checked and spelled, for every cache here.
+ * How a cache key is checked, spelled and ordered, for every cache here.
  *
- * LambderDdbCache and LambderMemoryCache take the same keys, and a key one of
- * them refuses has to be refused by the other: a test that runs over the
- * memory cache must not accept a key production then throws on. So the rules
- * are written once, here, and both stores normalize through them.
+ * LambderDdbCache, LambderMemoryCache and LambderStorageBackedCache take the
+ * same keys, and a key one of them refuses has to be refused by the others: a
+ * test that runs over the memory cache must not accept a key production then
+ * throws on. So the rules are written once, here, and every cache normalizes
+ * through them.
  */
 /** Longest partition accepted, in UTF-8 bytes. */
 const MAX_PARTITION_BYTES = 8 * 1024;
@@ -18,11 +19,29 @@ const utf8Bytes = (value) => new TextEncoder().encode(value).length;
  * `<encoded>#` an unambiguous boundary for prefix queries. Escaping is
  * per-character, so a prefix of the raw key stays a prefix of the encoded
  * one; only the sort ORDER of keys that contain `#` or `~` shifts, since both
- * encode into the `~` range. The memory cache sorts by the same encoding, so
- * listSortKeys answers in the same order over either store.
+ * encode into the `~` range. The other caches sort by the same encoding (see
+ * compareCacheSortKeys), so listSortKeys answers in the same order over any.
  */
 export const encodeCacheSortKey = (value) => value.replace(/~/g, "~0").replace(/#/g, "~1");
 export const decodeCacheSortKey = (value) => value.replace(/~([01])/g, (_match, code) => code === "0" ? "~" : "#");
+/** DynamoDB orders string range keys by their UTF-8 bytes, which is not JavaScript's UTF-16 order for every character. */
+const compareUtf8 = (first, second) => {
+    const a = new TextEncoder().encode(first);
+    const b = new TextEncoder().encode(second);
+    const length = Math.min(a.length, b.length);
+    for (let index = 0; index < length; index += 1) {
+        if (a[index] !== b[index])
+            return a[index] - b[index];
+    }
+    return a.length - b.length;
+};
+/**
+ * Orders two sort keys as LambderDdbCache lists them, for the caches that
+ * sort a listing themselves: by the whole item sort key the table ranges
+ * over, which carries a "#" after the encoded key. So "New York City" sorts
+ * before "New York" (" " is below "#"), over every cache alike.
+ */
+export const compareCacheSortKeys = (first, second) => compareUtf8(`${encodeCacheSortKey(first)}#`, `${encodeCacheSortKey(second)}#`);
 /** Length-prefixed so a partition ending in the separator cannot collide with a sort key. */
 export const cacheMemoryKeyOf = (partition, sortKey) => `${partition.length}:${partition}#${sortKey ?? ""}`;
 /** A partition as the caches accept it, or a throw naming what is wrong with it. */

package/dist/stores/LambderCacheValues.d.ts

@@ -34,9 +34,9 @@ export declare const resolveCacheTtlSeconds: (ttlSeconds: number | undefined, de
  * cache failing: every call would log, hand the loader's value back
  * uncached, and caching would be off without the caller ever seeing why.
  *
- * The lease options are LambderDdbCache's. The memory cache holds no lease
- * but checks them all the same, so an options object that the table refuses
- * is refused by its twin too.
+ * The lease options are LambderDdbCache's. The other caches hold no lease
+ * but check them all the same, so an options object that the table refuses
+ * is refused by every cache.
  */
 export declare const resolveGetOrSetOptions: (options: {
     ttlSeconds?: number;

package/dist/stores/LambderCacheValues.js

@@ -3,10 +3,11 @@ import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
  * What a cache value has to be, and how a cache call's options are read, for
  * every cache here.
  *
- * LambderDdbCache and LambderMemoryCache refuse the same values and the same
- * options for the reason they refuse the same keys (see LambderCacheKeys): a
- * test that runs over the memory cache must not accept what production then
- * throws on. So the rules are written once, here, and both caches call them.
+ * LambderDdbCache, LambderMemoryCache and LambderStorageBackedCache refuse the
+ * same values and the same options for the reason they refuse the same keys
+ * (see LambderCacheKeys): a test that runs over the memory cache must not
+ * accept what production then throws on. So the rules are written once, here,
+ * and every cache calls them.
  */
 /** How long an entry lives when neither the call nor the cache names a TTL: one year. */
 export const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
@@ -53,9 +54,9 @@ export const resolveCacheTtlSeconds = (ttlSeconds, defaultTtlSeconds) => assertP
  * cache failing: every call would log, hand the loader's value back
  * uncached, and caching would be off without the caller ever seeing why.
  *
- * The lease options are LambderDdbCache's. The memory cache holds no lease
- * but checks them all the same, so an options object that the table refuses
- * is refused by its twin too.
+ * The lease options are LambderDdbCache's. The other caches hold no lease
+ * but check them all the same, so an options object that the table refuses
+ * is refused by every cache.
  */
 export const resolveGetOrSetOptions = (options, defaultTtlSeconds) => {
     const leaseSeconds = assertPositiveInteger(options.leaseSeconds ?? DEFAULT_LEASE_SECONDS, "leaseSeconds");

package/dist/stores/LambderDdbCache.d.ts

@@ -80,7 +80,7 @@ export declare class LambderDdbCache implements LambderCache {
     private readonly compression;
     private readonly maxValueBytes;
     private readonly memory;
-    /** getOrSet's single-flight and fail-open, shared with LambderMemoryCache (see LambderCacheFiller). */
+    /** getOrSet's single-flight and fail-open, shared with the other caches (see LambderCacheFiller). */
     private readonly filler;
     private readonly now;
     /** This instance's own writes, as its reads and its memory layer need to know them (see LocalWriteLedger). */

package/dist/stores/LambderDdbCache.js

@@ -202,7 +202,7 @@ export class LambderDdbCache {
     compression;
     maxValueBytes;
     memory;
-    /** getOrSet's single-flight and fail-open, shared with LambderMemoryCache (see LambderCacheFiller). */
+    /** getOrSet's single-flight and fail-open, shared with the other caches (see LambderCacheFiller). */
     filler;
     now;
     /** This instance's own writes, as its reads and its memory layer need to know them (see LocalWriteLedger). */

package/dist/stores/LambderMemoryCache.d.ts

@@ -16,7 +16,7 @@ export interface LambderMemoryCacheOptions {
  * refuses, stores a value's JSON text and hands back a fresh parse of it,
  * expires entries on the same TTL, and lists sort keys in the same order.
  *
- * getOrSet runs through the LambderCacheFiller both caches hold: concurrent
+ * getOrSet runs through the LambderCacheFiller every cache holds: concurrent
  * calls for one key share a load, every call (the filling one included)
  * answers the stored JSON parsed, a loader's undefined comes back uncached,
  * and a set, delete or deletePartition of the key while the loader runs
@@ -29,7 +29,7 @@ export interface LambderMemoryCacheOptions {
  */
 export declare class LambderMemoryCache implements LambderCache {
     private readonly entries;
-    /** getOrSet's single-flight and fail-open, shared with LambderDdbCache (see LambderCacheFiller). */
+    /** getOrSet's single-flight and fail-open, shared with the other caches (see LambderCacheFiller). */
     private readonly filler;
     private readonly defaultTtlSeconds;
     private readonly maxValueBytes;

package/dist/stores/LambderMemoryCache.js

@@ -1,19 +1,8 @@
 import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
 import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
-import { cacheMemoryKeyOf, encodeCacheSortKey, normalizeCacheKey, normalizeCachePartition } from "./LambderCacheKeys.js";
+import { cacheMemoryKeyOf, compareCacheSortKeys, normalizeCacheKey, normalizeCachePartition } from "./LambderCacheKeys.js";
 import { DEFAULT_MAX_VALUE_BYTES, DEFAULT_TTL_SECONDS, resolveCacheTtlSeconds, resolveGetOrSetOptions, serializeCacheValue, } from "./LambderCacheValues.js";
 import { LambderCacheFiller } from "./LambderCacheFiller.js";
-/** DynamoDB orders string range keys by their UTF-8 bytes, which is not JavaScript's UTF-16 order for every character. */
-const compareUtf8 = (first, second) => {
-    const a = new TextEncoder().encode(first);
-    const b = new TextEncoder().encode(second);
-    const length = Math.min(a.length, b.length);
-    for (let index = 0; index < length; index += 1) {
-        if (a[index] !== b[index])
-            return a[index] - b[index];
-    }
-    return a.length - b.length;
-};
 /**
  * LambderDdbCache's twin, held in memory: the same LambderCache interface and
  * the same rules, so code written against the interface can be tested
@@ -21,7 +10,7 @@ const compareUtf8 = (first, second) => {
  * refuses, stores a value's JSON text and hands back a fresh parse of it,
  * expires entries on the same TTL, and lists sort keys in the same order.
  *
- * getOrSet runs through the LambderCacheFiller both caches hold: concurrent
+ * getOrSet runs through the LambderCacheFiller every cache holds: concurrent
  * calls for one key share a load, every call (the filling one included)
  * answers the stored JSON parsed, a loader's undefined comes back uncached,
  * and a set, delete or deletePartition of the key while the loader runs
@@ -34,7 +23,7 @@ const compareUtf8 = (first, second) => {
  */
 export class LambderMemoryCache {
     entries;
-    /** getOrSet's single-flight and fail-open, shared with LambderDdbCache (see LambderCacheFiller). */
+    /** getOrSet's single-flight and fail-open, shared with the other caches (see LambderCacheFiller). */
     filler = new LambderCacheFiller("Memory cache failed open");
     defaultTtlSeconds;
     maxValueBytes;
@@ -83,11 +72,7 @@ export class LambderMemoryCache {
         const limit = options.limit === undefined ? undefined : assertPositiveInteger(options.limit, "limit");
         const sortKeys = this.entries.values()
             .flatMap(({ address }) => address.partition === normalized && address.sortKey !== null && address.sortKey.startsWith(prefix) ? [address.sortKey] : [])
-            // Ordered as the table orders the items it lists: by the whole
-            // item sort key, which carries a "#" after the encoded key. So
-            // "New York City" sorts before "New York" there (" " is below
-            // "#"), and here too.
-            .sort((first, second) => compareUtf8(`${encodeCacheSortKey(first)}#`, `${encodeCacheSortKey(second)}#`));
+            .sort(compareCacheSortKeys);
         return limit === undefined ? sortKeys : sortKeys.slice(0, limit);
     }
     async getOrSet(key, loader, options = {}) {

package/dist/stores/LambderStorageBackedCache.d.ts

@@ -0,0 +1,95 @@
+import type { LambderCache, LambderCacheKey, LambderCacheListOptions, LambderCacheSetOptions } from "../shared/contracts/LambderCache.js";
+import { type LambderCacheAddress } from "./LambderCacheKeys.js";
+/** One entry as a storage keeps it: the value's JSON text and the second it stops being live. */
+export interface LambderCacheStoredEntry {
+    json: string;
+    /** Epoch seconds: the entry is live while this is greater than the current second, so it expires at this second itself. */
+    expiresAt: number;
+}
+/**
+ * Where a LambderStorageBackedCache keeps its entries: a SQL table, a Redis
+ * database, anything that can hold a JSON text and an expiry under an
+ * address. Only reading and writing are asked of it; the key checks, the
+ * JSON round trip, the TTL, the listing order and getOrSet's single-flight
+ * are the cache's, so no storage can drift from the rules the other caches
+ * keep.
+ *
+ * An entry is live at `nowSeconds` while its `expiresAt` is greater than
+ * `nowSeconds`. The cache hands `nowSeconds` to the methods that answer
+ * about live entries, so a storage can filter in its own query. It never
+ * removes an expired entry it is not asked to, so a storage purges them on
+ * its own schedule (a periodic delete, a native TTL) or grows without bound.
+ *
+ * A plain string key and the `{ pk, sk }` keys of one partition share that
+ * partition: `address.sortKey` is null for the plain one.
+ */
+export interface LambderCacheStorage {
+    /** The entry at this address, expired or not: the cache decides what is live. Null when there is none. */
+    read(address: LambderCacheAddress): Promise<LambderCacheStoredEntry | null>;
+    /** Creates the entry at this address, or replaces the one there. */
+    write(address: LambderCacheAddress, entry: LambderCacheStoredEntry): Promise<void>;
+    /** Removes the entry at this address, live or not; true when it was live at `nowSeconds`. */
+    delete(address: LambderCacheAddress, nowSeconds: number): Promise<boolean>;
+    /** Removes every entry under the partition, plain key and sort keys alike, and answers how many of them were live at `nowSeconds`. */
+    deletePartition(partition: string, nowSeconds: number): Promise<number>;
+    /**
+     * Every sort key under the partition that starts with `prefix` and is
+     * live at `nowSeconds`, in any order: the cache sorts the list and cuts
+     * it to the caller's limit. A plain key's entry has no sort key and is
+     * never listed.
+     */
+    listSortKeys(partition: string, prefix: string, nowSeconds: number): Promise<string[]>;
+}
+export interface LambderStorageBackedCacheOptions {
+    /** Where the entries live. */
+    storage: LambderCacheStorage;
+    /** Default: one year, as the other caches'. */
+    defaultTtlSeconds?: number;
+    /** Largest value accepted, in UTF-8 bytes of its JSON. Default: 32 MiB, as the other caches'. */
+    maxValueBytes?: number;
+    /** The clock entries expire against, in epoch milliseconds, so a test can cross a TTL without waiting. */
+    now?: () => number;
+}
+/**
+ * A LambderCache over storage the app supplies (see LambderCacheStorage),
+ * with every rule LambderMemoryCache keeps: it refuses the keys and values
+ * the other caches refuse, stores a value's JSON text and hands back a fresh
+ * parse of it, expires entries on the same TTL, counts only live entries in
+ * what delete and deletePartition answer, and lists sort keys in the table's
+ * order whatever order the storage finds them in.
+ *
+ * getOrSet runs through the LambderCacheFiller every cache holds: concurrent
+ * calls for one key in this process share a load, every call answers the
+ * stored JSON parsed, a loader's undefined comes back uncached, a set,
+ * delete or deletePartition of the key while the loader runs keeps the fill
+ * from storing over it, and a storage that fails (a read, a write) hands the
+ * loader's value back uncached rather than failing the caller. A fill whose
+ * write is already on its way to the storage when a write of the same key
+ * arrives races it there, as two overlapping sets do.
+ *
+ * It holds no fill lease across processes: two processes missing one key
+ * each run the loader, and the last write stands. It keeps nothing in
+ * memory either, so every read asks the storage.
+ */
+export declare class LambderStorageBackedCache implements LambderCache {
+    private readonly storage;
+    /** getOrSet's single-flight and fail-open, shared with the other caches (see LambderCacheFiller). */
+    private readonly filler;
+    private readonly defaultTtlSeconds;
+    private readonly maxValueBytes;
+    private readonly now;
+    constructor(options: LambderStorageBackedCacheOptions);
+    get<T>(key: LambderCacheKey): Promise<T | undefined>;
+    has(key: LambderCacheKey): Promise<boolean>;
+    set<T>(key: LambderCacheKey, value: T, options?: LambderCacheSetOptions): Promise<void>;
+    delete(key: LambderCacheKey): Promise<boolean>;
+    deletePartition(partition: string): Promise<number>;
+    listSortKeys(partition: string, options?: LambderCacheListOptions): Promise<string[]>;
+    getOrSet<T>(key: LambderCacheKey, loader: () => Promise<T>, options?: LambderCacheSetOptions): Promise<T>;
+    /** Whole seconds, as entries expire in every cache here, so a TTL ends on the same second as the memory cache's. */
+    private nowSeconds;
+    /** The entry at the address while it is live; the storage may still hold one past its expiry. */
+    private readLive;
+    /** Stores the value and hands back what was stored, the parse of its JSON. */
+    private setByAddress;
+}

package/dist/stores/LambderStorageBackedCache.js

@@ -0,0 +1,97 @@
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
+import { cacheMemoryKeyOf, compareCacheSortKeys, normalizeCacheKey, normalizeCachePartition } from "./LambderCacheKeys.js";
+import { DEFAULT_MAX_VALUE_BYTES, DEFAULT_TTL_SECONDS, resolveCacheTtlSeconds, resolveGetOrSetOptions, serializeCacheValue, } from "./LambderCacheValues.js";
+import { LambderCacheFiller } from "./LambderCacheFiller.js";
+/**
+ * A LambderCache over storage the app supplies (see LambderCacheStorage),
+ * with every rule LambderMemoryCache keeps: it refuses the keys and values
+ * the other caches refuse, stores a value's JSON text and hands back a fresh
+ * parse of it, expires entries on the same TTL, counts only live entries in
+ * what delete and deletePartition answer, and lists sort keys in the table's
+ * order whatever order the storage finds them in.
+ *
+ * getOrSet runs through the LambderCacheFiller every cache holds: concurrent
+ * calls for one key in this process share a load, every call answers the
+ * stored JSON parsed, a loader's undefined comes back uncached, a set,
+ * delete or deletePartition of the key while the loader runs keeps the fill
+ * from storing over it, and a storage that fails (a read, a write) hands the
+ * loader's value back uncached rather than failing the caller. A fill whose
+ * write is already on its way to the storage when a write of the same key
+ * arrives races it there, as two overlapping sets do.
+ *
+ * It holds no fill lease across processes: two processes missing one key
+ * each run the loader, and the last write stands. It keeps nothing in
+ * memory either, so every read asks the storage.
+ */
+export class LambderStorageBackedCache {
+    storage;
+    /** getOrSet's single-flight and fail-open, shared with the other caches (see LambderCacheFiller). */
+    filler = new LambderCacheFiller("Storage-backed cache failed open");
+    defaultTtlSeconds;
+    maxValueBytes;
+    now;
+    constructor(options) {
+        // Here rather than at first use, where getOrSet would fail open over
+        // it on every call and caching would be off without a caller seeing why.
+        if (!options.storage)
+            throw new Error("storage is required");
+        this.storage = options.storage;
+        this.now = options.now ?? (() => Date.now());
+        this.defaultTtlSeconds = assertPositiveInteger(options.defaultTtlSeconds ?? DEFAULT_TTL_SECONDS, "defaultTtlSeconds");
+        this.maxValueBytes = assertPositiveInteger(options.maxValueBytes ?? DEFAULT_MAX_VALUE_BYTES, "maxValueBytes");
+    }
+    async get(key) {
+        const entry = await this.readLive(normalizeCacheKey(key));
+        return entry ? JSON.parse(entry.json) : undefined;
+    }
+    async has(key) {
+        return await this.readLive(normalizeCacheKey(key)) !== null;
+    }
+    async set(key, value, options = {}) {
+        const address = normalizeCacheKey(key);
+        const ttlSeconds = resolveCacheTtlSeconds(options.ttlSeconds, this.defaultTtlSeconds);
+        this.filler.supersedeFill(address.memoryKey);
+        await this.setByAddress(address, value, ttlSeconds);
+    }
+    async delete(key) {
+        const address = normalizeCacheKey(key);
+        this.filler.supersedeFill(address.memoryKey);
+        return await this.storage.delete(address, this.nowSeconds());
+    }
+    async deletePartition(partition) {
+        const normalized = normalizeCachePartition(partition);
+        this.filler.supersedeFillsWithPrefix(cacheMemoryKeyOf(normalized, ""));
+        return await this.storage.deletePartition(normalized, this.nowSeconds());
+    }
+    async listSortKeys(partition, options = {}) {
+        const normalized = normalizeCachePartition(partition);
+        const prefix = options.prefix ?? "";
+        const limit = options.limit === undefined ? undefined : assertPositiveInteger(options.limit, "limit");
+        // A copy, since the storage may hand back a list it holds on to.
+        const sortKeys = [...await this.storage.listSortKeys(normalized, prefix, this.nowSeconds())].sort(compareCacheSortKeys);
+        return limit === undefined ? sortKeys : sortKeys.slice(0, limit);
+    }
+    async getOrSet(key, loader, options = {}) {
+        const address = normalizeCacheKey(key);
+        const { ttlSeconds } = resolveGetOrSetOptions(options, this.defaultTtlSeconds);
+        return this.filler.getOrSet(address.memoryKey, loader, async (load) => {
+            const existing = await this.readLive(address);
+            return existing ? JSON.parse(existing.json) : await load(async (value) => await this.setByAddress(address, value, ttlSeconds));
+        });
+    }
+    /** Whole seconds, as entries expire in every cache here, so a TTL ends on the same second as the memory cache's. */
+    nowSeconds() {
+        return Math.floor(this.now() / 1000);
+    }
+    /** The entry at the address while it is live; the storage may still hold one past its expiry. */
+    async readLive(address) {
+        const entry = await this.storage.read(address);
+        return entry && entry.expiresAt > this.nowSeconds() ? entry : null;
+    }
+    /** Stores the value and hands back what was stored, the parse of its JSON. */
+    async setByAddress(address, value, ttlSeconds) {
+        const { json } = serializeCacheValue(value, this.maxValueBytes);
+        await this.storage.write(address, { json, expiresAt: this.nowSeconds() + ttlSeconds });
+        return JSON.parse(json);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "10.1.1",
+  "version": "11.0.1",
   "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": [