lambder 10.1.1 → 10.2.1

package/CHANGELOG.md

@@ -9,6 +9,35 @@ 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.
 
+## [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/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";

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": "10.2.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": [