lambder 14.1.1 → 15.0.2

package/dist/testing/lambderCacheConformance.js

@@ -0,0 +1,287 @@
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/** A loader that answers only once the case opens its gate, and lets the case wait until it has been called. */
+const gatedLoader = (value) => {
+    let open = () => undefined;
+    let markStarted = () => undefined;
+    const gate = new Promise((resolve) => { open = resolve; });
+    const started = new Promise((resolve) => { markStarted = resolve; });
+    let calls = 0;
+    const loader = async () => {
+        calls += 1;
+        markStarted();
+        await gate;
+        return value;
+    };
+    return { loader, started, open: () => open(), calls: () => calls };
+};
+/** A loader that counts its calls. */
+const countingLoader = (answer) => {
+    let calls = 0;
+    return { loader: async () => { calls += 1; return answer(); }, calls: () => calls };
+};
+/**
+ * Registers the cache rules as cases of the runner, one `it` each, against
+ * the cache `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderCacheConformance } from "lambder/testing";
+ *
+ * describe("RedisCache", () => {
+ *     lambderCacheConformance({ it, expect, create: async ({ now }) => { await emptyCache(); return new RedisCache({ client, now }); } });
+ * });
+ * ```
+ *
+ * The entries a case writes expire by the case's clock, which starts at a
+ * fixed moment far in the future and stands still unless a case moves it: a
+ * cache that expires entries by the system clock, rather than by `now`, never
+ * sees one expire. A cache over a storage with a native TTL keeps it on, since
+ * nothing a case writes has expired by the world's clock.
+ */
+export const lambderCacheConformance = (options) => {
+    const { it, expect } = options;
+    const begin = async () => {
+        const clock = conformanceClock();
+        return { clock, cache: await options.create(clock) };
+    };
+    it("hands back a parse of what was stored, never the object itself", async () => {
+        const { cache } = await begin();
+        const value = { list: [1, 2], at: new Date(START) };
+        await cache.set("round-trip", value);
+        value.list.push(3);
+        const read = await cache.get("round-trip");
+        expect(read).toEqual({ list: [1, 2], at: new Date(START).toISOString() });
+        expect(await cache.get("round-trip")).not.toBe(read);
+    });
+    it("answers undefined for an absent key and false from has()", async () => {
+        const { cache } = await begin();
+        expect(await cache.get("absent")).toBeUndefined();
+        expect(await cache.has("absent")).toBe(false);
+    });
+    it("replaces an entry on a second set", async () => {
+        const { cache } = await begin();
+        await cache.set("order:1001", { status: "placed" });
+        await cache.set("order:1001", { status: "shipped" });
+        expect(await cache.get("order:1001")).toEqual({ status: "shipped" });
+        expect(await cache.has("order:1001")).toBe(true);
+    });
+    it("expires an entry at its TTL, the expiry second itself included", async () => {
+        const { clock, cache } = await begin();
+        await cache.set("short", "value", { ttlSeconds: 10 });
+        clock.set(START + 9_000);
+        expect(await cache.get("short")).toBe("value");
+        expect(await cache.has("short")).toBe(true);
+        clock.set(START + 10_000);
+        expect(await cache.get("short")).toBeUndefined();
+        expect(await cache.has("short")).toBe(false);
+    });
+    it("refuses a value JSON cannot represent, a blank key, and a sort key past 900 bytes once escaped", async () => {
+        const { cache } = await begin();
+        await expect(cache.set("nothing", undefined)).rejects.toThrow();
+        await expect(cache.get("  ")).rejects.toThrow();
+        await expect(cache.get({ pk: "reports", sk: "  " })).rejects.toThrow();
+        // "#" escapes to two bytes, so 500 of them are 1000 bytes escaped.
+        await expect(cache.get({ pk: "reports", sk: "#".repeat(500) })).rejects.toThrow();
+    });
+    it("deletes one entry and says whether there was one", async () => {
+        const { cache } = await begin();
+        await cache.set("gone", 1);
+        expect(await cache.delete("gone")).toBe(true);
+        expect(await cache.get("gone")).toBeUndefined();
+        expect(await cache.delete("gone")).toBe(false);
+    });
+    it("keeps a plain key and the grouped keys of its partition apart", async () => {
+        const { cache } = await begin();
+        await cache.set("store:nyc-01", "a plain key");
+        await cache.set({ pk: "store:nyc-01", sk: "hours" }, "a grouped key");
+        expect(await cache.delete("store:nyc-01")).toBe(true);
+        expect(await cache.get({ pk: "store:nyc-01", sk: "hours" })).toBe("a grouped key");
+        await cache.set("store:nyc-01", "a plain key");
+        expect(await cache.delete({ pk: "store:nyc-01", sk: "hours" })).toBe(true);
+        expect(await cache.get("store:nyc-01")).toBe("a plain key");
+    });
+    it("answers false from delete while a fill is loading the key, since a load in progress is no entry", async () => {
+        const { cache } = await begin();
+        const { loader, started, open } = gatedLoader({ tag: "old" });
+        const fill = cache.getOrSet("filling", loader);
+        await started;
+        expect(await cache.delete("filling")).toBe(false);
+        open();
+        expect(await fill).toEqual({ tag: "old" });
+        expect(await cache.get("filling")).toBeUndefined();
+    });
+    it("counts no entry past its TTL as deleted, from delete or deletePartition", async () => {
+        const { clock, cache } = await begin();
+        await cache.set("short", 1, { ttlSeconds: 10 });
+        await cache.set({ pk: "store", sk: "short" }, 2, { ttlSeconds: 10 });
+        await cache.set({ pk: "store", sk: "long" }, 3, { ttlSeconds: 100 });
+        clock.set(START + 10_000);
+        expect(await cache.delete("short")).toBe(false);
+        expect(await cache.deletePartition("store")).toBe(1);
+    });
+    it("lists a partition's sort keys in order, by prefix and up to a limit, and leaves plain keys out", async () => {
+        const { cache } = await begin();
+        await cache.set({ pk: "store", sk: "1800:1900" }, 3);
+        await cache.set({ pk: "store", sk: "1700:1800" }, 2);
+        await cache.set({ pk: "store", sk: "0900:1000" }, 1);
+        await cache.set({ pk: "other", sk: "1700:1800" }, 4);
+        await cache.set("store", "a plain key sharing the partition");
+        expect(await cache.listSortKeys("store")).toEqual(["0900:1000", "1700:1800", "1800:1900"]);
+        expect(await cache.listSortKeys("store", { prefix: "1" })).toEqual(["1700:1800", "1800:1900"]);
+        expect(await cache.listSortKeys("store", { limit: 1 })).toEqual(["0900:1000"]);
+        expect(await cache.listSortKeys("nothing-here")).toEqual([]);
+    });
+    it("lists only live sort keys", async () => {
+        const { clock, cache } = await begin();
+        await cache.set({ pk: "store", sk: "short" }, 1, { ttlSeconds: 10 });
+        await cache.set({ pk: "store", sk: "long" }, 2, { ttlSeconds: 100 });
+        clock.set(START + 10_000);
+        expect(await cache.listSortKeys("store")).toEqual(["long"]);
+    });
+    it("orders a key before one it is a prefix of when the longer one goes on below \"#\", as the table does", async () => {
+        const { cache } = await begin();
+        await cache.set({ pk: "cities", sk: "New York" }, 1);
+        await cache.set({ pk: "cities", sk: "New York City" }, 2);
+        await cache.set({ pk: "cities", sk: "New Yorker" }, 3);
+        expect(await cache.listSortKeys("cities")).toEqual(["New York City", "New York", "New Yorker"]);
+        expect(await cache.listSortKeys("cities", { prefix: "New", limit: 1 })).toEqual(["New York City"]);
+    });
+    it("orders keys holding \"#\" or \"~\" by their escaped form, as the table ranges them", async () => {
+        const { cache } = await begin();
+        await cache.set({ pk: "reports", sk: "a#b" }, 1);
+        await cache.set({ pk: "reports", sk: "a~b" }, 2);
+        await cache.set({ pk: "reports", sk: "a~1b" }, 3);
+        await cache.set({ pk: "reports", sk: "ab" }, 4);
+        // "~" escapes as "~0" and "#" as "~1", so both land past every letter.
+        expect(await cache.listSortKeys("reports")).toEqual(["ab", "a~1b", "a~b", "a#b"]);
+        expect(await cache.listSortKeys("reports", { prefix: "a~" })).toEqual(["a~1b", "a~b"]);
+    });
+    it("orders sort keys by their UTF-8 bytes, as DynamoDB orders a range key", async () => {
+        const { cache } = await begin();
+        // By bytes "B" (0x42) sorts before "a" (0x61), the opposite of a
+        // locale compare, and U+FF5E (0xEF ...) before U+1F600 (0xF0 ...),
+        // the opposite of UTF-16, which puts the surrogate pair first.
+        await cache.set({ pk: "p", sk: "a" }, 1);
+        await cache.set({ pk: "p", sk: "B" }, 2);
+        await cache.set({ pk: "p", sk: "\uff5e" }, 3);
+        await cache.set({ pk: "p", sk: "\u{1f600}" }, 4);
+        expect(await cache.listSortKeys("p")).toEqual(["B", "a", "\uff5e", "\u{1f600}"]);
+    });
+    it("drops a partition's grouped entries in one call and counts them", async () => {
+        const { cache } = await begin();
+        await cache.set({ pk: "store", sk: "a" }, 1);
+        await cache.set({ pk: "store", sk: "b" }, 2);
+        await cache.set({ pk: "other", sk: "a" }, 3);
+        expect(await cache.deletePartition("store")).toBe(2);
+        expect(await cache.listSortKeys("store")).toEqual([]);
+        expect(await cache.get({ pk: "other", sk: "a" })).toBe(3);
+    });
+    it("drops and counts a plain key sharing the partition, and leaves other partitions' plain keys alone", async () => {
+        const { cache } = await begin();
+        await cache.set("store", "a plain key sharing the partition");
+        await cache.set({ pk: "store", sk: "a" }, 1);
+        await cache.set("other", "a plain key of its own");
+        await cache.set("store:nyc-01", "a partition the first is a prefix of");
+        expect(await cache.deletePartition("store")).toBe(2);
+        expect(await cache.get("store")).toBeUndefined();
+        expect(await cache.get("other")).toBe("a plain key of its own");
+        expect(await cache.get("store:nyc-01")).toBe("a partition the first is a prefix of");
+    });
+    it("loads once for concurrent getOrSet calls, then serves what it stored", async () => {
+        const { cache } = await begin();
+        const { loader, calls } = countingLoader(() => ({ city: "New York" }));
+        const [first, second] = await Promise.all([cache.getOrSet("city", loader), cache.getOrSet("city", loader)]);
+        expect(first).toEqual({ city: "New York" });
+        expect(second).toEqual({ city: "New York" });
+        expect(calls()).toBe(1);
+        expect(await cache.getOrSet("city", loader)).toEqual({ city: "New York" });
+        expect(calls()).toBe(1);
+        expect(await cache.get("city")).toEqual({ city: "New York" });
+    });
+    it("stores a getOrSet value under the call's TTL", async () => {
+        const { clock, cache } = await begin();
+        await cache.getOrSet("short", async () => "value", { ttlSeconds: 10 });
+        clock.set(START + 9_000);
+        expect(await cache.get("short")).toBe("value");
+        clock.set(START + 10_000);
+        expect(await cache.get("short")).toBeUndefined();
+    });
+    it("hands each call that shares a load or a read a parse of its own", async () => {
+        const { cache } = await begin();
+        const loader = async () => ({ list: [1] });
+        const [first, second] = await Promise.all([cache.getOrSet("shared", loader), cache.getOrSet("shared", loader)]);
+        expect(second).not.toBe(first);
+        first.list.push(2);
+        expect(second).toEqual({ list: [1] });
+        const [hit, joiner] = await Promise.all([cache.getOrSet("shared", loader), cache.getOrSet("shared", loader)]);
+        expect(joiner).not.toBe(hit);
+        expect(joiner).toEqual({ list: [1] });
+    });
+    it("leaves a loader's undefined uncached and asks the loader again next time", async () => {
+        const { cache } = await begin();
+        const { loader, calls } = countingLoader(() => undefined);
+        expect(await cache.getOrSet("not-found", loader)).toBeUndefined();
+        expect(await cache.has("not-found")).toBe(false);
+        expect(await cache.getOrSet("not-found", loader)).toBeUndefined();
+        expect(calls()).toBe(2);
+    });
+    it("caches a loader's null, the way to cache \"not found\"", async () => {
+        const { cache } = await begin();
+        const { loader, calls } = countingLoader(() => null);
+        expect(await cache.getOrSet("not-found", loader)).toBeNull();
+        expect(await cache.getOrSet("not-found", loader)).toBeNull();
+        expect(calls()).toBe(1);
+        expect(await cache.has("not-found")).toBe(true);
+    });
+    it("answers the stored JSON on the call that filled the entry, as on every later one", async () => {
+        const { cache } = await begin();
+        const loader = async () => ({ at: new Date("2026-01-02T03:04:05.000Z"), gone: undefined, count: 1 });
+        const first = await cache.getOrSet("shape", loader);
+        const later = await cache.getOrSet("shape", loader);
+        expect(first).toEqual({ at: "2026-01-02T03:04:05.000Z", count: 1 });
+        expect(Object.keys(first)).toEqual(["at", "count"]);
+        expect(later).toEqual(first);
+    });
+    it("propagates a loader that throws, and stores nothing", async () => {
+        const { cache } = await begin();
+        await expect(cache.getOrSet("broken", async () => { throw new Error("origin down"); })).rejects.toThrow();
+        expect(await cache.has("broken")).toBe(false);
+    });
+    it("never stores a slow fill's value over a set and a delete that landed while it loaded", async () => {
+        const { cache } = await begin();
+        const { loader, started, open } = gatedLoader({ tag: "old" });
+        const fill = cache.getOrSet("raced", loader);
+        await started;
+        await cache.set("raced", { tag: "new" });
+        // A call after the write reads it, rather than joining the load it overtook.
+        expect(await cache.getOrSet("raced", async () => ({ tag: "other" }))).toEqual({ tag: "new" });
+        await cache.delete("raced");
+        open();
+        expect(await fill).toEqual({ tag: "old" });
+        expect(await cache.get("raced")).toBeUndefined();
+    });
+    it("never stores a slow fill's value over a deletePartition that landed while it loaded", async () => {
+        const { cache } = await begin();
+        const key = { pk: "store", sk: "a" };
+        const { loader, started, open } = gatedLoader({ tag: "old" });
+        const fill = cache.getOrSet(key, loader);
+        await started;
+        expect(await cache.deletePartition("store")).toBe(0);
+        open();
+        expect(await fill).toEqual({ tag: "old" });
+        expect(await cache.get(key)).toBeUndefined();
+    });
+    it("throws an invalid option to the caller before loading anything", async () => {
+        const { cache } = await begin();
+        const { loader, calls } = countingLoader(() => "value");
+        await expect(cache.set("options", 1, { ttlSeconds: 0 })).rejects.toThrow();
+        await expect(cache.getOrSet("options", loader, { ttlSeconds: 0 })).rejects.toThrow();
+        await expect(cache.getOrSet("options", loader, { ttlSeconds: 1.5 })).rejects.toThrow();
+        // The fill lease's options are checked by every cache, whether or not it holds a lease.
+        await expect(cache.getOrSet("options", loader, { leaseSeconds: 0 })).rejects.toThrow();
+        await expect(cache.getOrSet("options", loader, { waitForFillMs: 1.5 })).rejects.toThrow();
+        await expect(cache.listSortKeys("store", { limit: 0 })).rejects.toThrow();
+        expect(calls()).toBe(0);
+        expect(await cache.has("options")).toBe(false);
+    });
+};

package/dist/testing/lambderCacheStorageConformance.d.ts

@@ -0,0 +1,25 @@
+import type { LambderCacheStorage } from "../stores/LambderStorageBackedCache.js";
+import { type LambderConformanceRunner } from "./LambderConformanceRunner.js";
+export type LambderCacheStorageConformanceOptions = LambderConformanceRunner & {
+    /**
+     * A storage holding no entries, built for one case. A storage over a
+     * database empties what the previous case wrote here, since cases reuse
+     * the same addresses. It is handed no clock: a storage judges no time
+     * itself, the cache hands it the second each question is about.
+     */
+    create: () => LambderCacheStorage | Promise<LambderCacheStorage>;
+};
+/**
+ * Registers the cache storage rules as cases of the runner, one `it` each,
+ * against the storage `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderCacheStorageConformance } from "lambder/testing";
+ *
+ * describe("cacheEntryTable", () => {
+ *     lambderCacheStorageConformance({ it, expect, create: async () => { await emptyCacheEntries(); return cacheEntryTable; } });
+ * });
+ * ```
+ */
+export declare const lambderCacheStorageConformance: (options: LambderCacheStorageConformanceOptions) => void;

package/dist/testing/lambderCacheStorageConformance.js

@@ -0,0 +1,159 @@
+import { normalizeCacheKey } from "../stores/LambderCacheKeys.js";
+import { CONFORMANCE_START_MILLIS } from "./LambderConformanceRunner.js";
+/**
+ * The second every case asks about: where every suite's clock starts, fixed
+ * and far in the future (see CONFORMANCE_START_MILLIS), so an entry counts as
+ * expired only by the storage's own answer to `nowSeconds`.
+ */
+const NOW = CONFORMANCE_START_MILLIS / 1000;
+/** The address the cache would hand the storage for a key. */
+const at = (key) => normalizeCacheKey(key);
+const live = (json) => ({ json, expiresAt: NOW + 3600 });
+/** An entry whose expiry is the very second asked about: no longer live, as the cache counts. */
+const expiring = (json) => ({ json, expiresAt: NOW });
+/** A listing in a fixed order, since a storage may answer in any. */
+const sorted = (keys) => [...keys].sort();
+/**
+ * Registers the cache storage rules as cases of the runner, one `it` each,
+ * against the storage `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderCacheStorageConformance } from "lambder/testing";
+ *
+ * describe("cacheEntryTable", () => {
+ *     lambderCacheStorageConformance({ it, expect, create: async () => { await emptyCacheEntries(); return cacheEntryTable; } });
+ * });
+ * ```
+ */
+export const lambderCacheStorageConformance = (options) => {
+    const { it, expect } = options;
+    const begin = async () => await options.create();
+    /** The JSON text an address holds, or null: what a case compares, whatever else the storage's entry carries. */
+    const jsonAt = async (storage, key) => (await storage.read(at(key)))?.json ?? null;
+    it("reads null at an address it holds nothing at", async () => {
+        const storage = await begin();
+        expect(await storage.read(at("order:1001"))).toBeNull();
+        expect(await storage.read(at({ pk: "store:nyc-01", sk: "hours" }))).toBeNull();
+    });
+    it("hands back what was written: the JSON text byte for byte, and the expiry second as a number", async () => {
+        const storage = await begin();
+        // Keys out of alphabetical order, escapes and characters past ASCII:
+        // a column that parses the JSON (jsonb) hands back other text.
+        const json = JSON.stringify({ zone: "America/New_York", items: [3, 1, 2], note: "Caf\u00e9 \u2615 \"two\"\nlines" });
+        await storage.write(at("order:1001"), { json, expiresAt: NOW + 60 });
+        await storage.write(at({ pk: "store:nyc-01", sk: "hours" }), { json: "null", expiresAt: NOW + 120 });
+        const plain = await storage.read(at("order:1001"));
+        expect(plain?.json).toBe(json);
+        expect(plain?.expiresAt).toBe(NOW + 60);
+        const grouped = await storage.read(at({ pk: "store:nyc-01", sk: "hours" }));
+        expect(grouped?.json).toBe("null");
+        expect(grouped?.expiresAt).toBe(NOW + 120);
+    });
+    it("replaces the entry at an address on a second write", async () => {
+        const storage = await begin();
+        await storage.write(at("order:1001"), live("\"placed\""));
+        await storage.write(at("order:1001"), { json: "\"shipped\"", expiresAt: NOW + 7200 });
+        const read = await storage.read(at("order:1001"));
+        expect(read?.json).toBe("\"shipped\"");
+        expect(read?.expiresAt).toBe(NOW + 7200);
+    });
+    it("keeps every address apart: a plain key, the sort keys of its partition, and partitions that share a prefix or a separator", async () => {
+        const storage = await begin();
+        const keys = [
+            "store",
+            { pk: "store", sk: "hours" },
+            { pk: "store", sk: "hours:late" },
+            "store:nyc-01",
+            { pk: "store:nyc-01", sk: "hours" },
+            // What a storage joining partition and sort key with "#" would file as { pk: "store", sk: "hours" }.
+            "store#hours",
+        ];
+        for (const [index, key] of keys.entries())
+            await storage.write(at(key), live(String(index)));
+        for (const [index, key] of keys.entries())
+            expect(await jsonAt(storage, key)).toBe(String(index));
+    });
+    it("tells apart keys a database collation may compare as equal: by case, and by a trailing space", async () => {
+        const storage = await begin();
+        const keys = [
+            "store", "Store", "store ",
+            { pk: "store", sk: "a" }, { pk: "store", sk: "A" }, { pk: "store", sk: "a " },
+        ];
+        for (const [index, key] of keys.entries())
+            await storage.write(at(key), live(String(index)));
+        for (const [index, key] of keys.entries())
+            expect(await jsonAt(storage, key)).toBe(String(index));
+        expect(sorted(await storage.listSortKeys("store", "", NOW))).toEqual(["A", "a", "a "]);
+    });
+    it("deletes one entry, answers whether it was live at the second asked about, and leaves the rest of its partition alone", async () => {
+        const storage = await begin();
+        await storage.write(at("store"), live("\"plain\""));
+        await storage.write(at({ pk: "store", sk: "a" }), live("1"));
+        await storage.write(at({ pk: "store", sk: "b" }), expiring("2"));
+        expect(await storage.delete(at("store"), NOW)).toBe(true);
+        expect(await storage.read(at("store"))).toBeNull();
+        expect(await jsonAt(storage, { pk: "store", sk: "a" })).toBe("1");
+        // Expired at that very second: removed all the same, and not counted as live.
+        expect(await storage.delete(at({ pk: "store", sk: "b" }), NOW)).toBe(false);
+        expect(await storage.read(at({ pk: "store", sk: "b" }))).toBeNull();
+        expect(await storage.delete(at({ pk: "store", sk: "a" }), NOW)).toBe(true);
+        expect(await storage.delete(at({ pk: "store", sk: "a" }), NOW)).toBe(false);
+        expect(await storage.delete(at("absent"), NOW)).toBe(false);
+    });
+    it("judges a deleted entry live by the second it is handed, not by its own clock", async () => {
+        const storage = await begin();
+        await storage.write(at("order:1001"), expiring("1"));
+        expect(await storage.delete(at("order:1001"), NOW - 1)).toBe(true);
+    });
+    it("drops every entry under a partition, the plain key's included, and counts the live ones", async () => {
+        const storage = await begin();
+        await storage.write(at("store"), live("\"plain\""));
+        await storage.write(at({ pk: "store", sk: "a" }), live("1"));
+        await storage.write(at({ pk: "store", sk: "b" }), expiring("2"));
+        await storage.write(at("store:nyc-01"), live("\"a partition 'store' is a prefix of\""));
+        await storage.write(at({ pk: "store:nyc-01", sk: "a" }), live("3"));
+        await storage.write(at({ pk: "Store", sk: "a" }), live("4"));
+        await storage.write(at({ pk: "other", sk: "a" }), live("5"));
+        expect(await storage.deletePartition("store", NOW)).toBe(2);
+        expect(await storage.read(at("store"))).toBeNull();
+        expect(await storage.read(at({ pk: "store", sk: "a" }))).toBeNull();
+        expect(await storage.read(at({ pk: "store", sk: "b" }))).toBeNull();
+        expect(await jsonAt(storage, "store:nyc-01")).toBe("\"a partition 'store' is a prefix of\"");
+        expect(await jsonAt(storage, { pk: "store:nyc-01", sk: "a" })).toBe("3");
+        expect(await jsonAt(storage, { pk: "Store", sk: "a" })).toBe("4");
+        expect(await jsonAt(storage, { pk: "other", sk: "a" })).toBe("5");
+        expect(await storage.deletePartition("store", NOW)).toBe(0);
+    });
+    it("counts a dropped partition's live entries by the second it is handed", async () => {
+        const storage = await begin();
+        await storage.write(at({ pk: "store", sk: "a" }), live("1"));
+        await storage.write(at({ pk: "store", sk: "b" }), expiring("2"));
+        expect(await storage.deletePartition("store", NOW - 1)).toBe(2);
+    });
+    it("lists the live sort keys under a partition, never the plain key's entry, by the second it is handed", async () => {
+        const storage = await begin();
+        await storage.write(at("store"), live("\"plain\""));
+        await storage.write(at({ pk: "store", sk: "1700:1800" }), live("1"));
+        await storage.write(at({ pk: "store", sk: "1800:1900" }), live("2"));
+        await storage.write(at({ pk: "store", sk: "0900:1000" }), expiring("3"));
+        await storage.write(at({ pk: "store:nyc-01", sk: "1700:1900" }), live("4"));
+        await storage.write(at({ pk: "other", sk: "1700:2000" }), live("5"));
+        expect(sorted(await storage.listSortKeys("store", "", NOW))).toEqual(["1700:1800", "1800:1900"]);
+        expect(sorted(await storage.listSortKeys("store", "17", NOW))).toEqual(["1700:1800"]);
+        expect(sorted(await storage.listSortKeys("store", "", NOW - 1))).toEqual(["0900:1000", "1700:1800", "1800:1900"]);
+        expect(await storage.listSortKeys("nothing-here", "", NOW)).toEqual([]);
+    });
+    it("matches a listing prefix literally, so characters a SQL pattern reads as wildcards match only themselves", async () => {
+        const storage = await begin();
+        for (const sortKey of ["a_b", "axb", "a%c", "abc", "a#b", "a~b", "a\\b"]) {
+            await storage.write(at({ pk: "store", sk: sortKey }), live("1"));
+        }
+        expect(sorted(await storage.listSortKeys("store", "a_", NOW))).toEqual(["a_b"]);
+        expect(sorted(await storage.listSortKeys("store", "a%", NOW))).toEqual(["a%c"]);
+        expect(sorted(await storage.listSortKeys("store", "a#", NOW))).toEqual(["a#b"]);
+        expect(sorted(await storage.listSortKeys("store", "a~", NOW))).toEqual(["a~b"]);
+        expect(sorted(await storage.listSortKeys("store", "a\\", NOW))).toEqual(["a\\b"]);
+        expect(await storage.listSortKeys("store", "a", NOW)).toHaveLength(7);
+    });
+};

package/dist/testing/lambderSessionStoreConformance.d.ts

@@ -20,8 +20,8 @@ export type LambderSessionStoreConformanceOptions = LambderConformanceRunner & {
  * ```
  *
  * The records a case writes are dated from the case's clock, which starts at
- * a fixed moment and stands still unless a case moves it: a store that
- * expires records by the system clock, rather than by `now`, finds them all
- * long expired.
+ * a fixed moment far in the future and stands still unless a case moves it: a
+ * store that expires records by the system clock, rather than by `now`, never
+ * sees one expire.
  */
 export declare const lambderSessionStoreConformance: (options: LambderSessionStoreConformanceOptions) => void;

package/dist/testing/lambderSessionStoreConformance.js

@@ -13,9 +13,9 @@ import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderC
  * ```
  *
  * The records a case writes are dated from the case's clock, which starts at
- * a fixed moment and stands still unless a case moves it: a store that
- * expires records by the system clock, rather than by `now`, finds them all
- * long expired.
+ * a fixed moment far in the future and stands still unless a case moves it: a
+ * store that expires records by the system clock, rather than by `now`, never
+ * sees one expire.
  */
 export const lambderSessionStoreConformance = (options) => {
     const { it, expect } = options;

package/dist/testing.d.ts

@@ -16,7 +16,7 @@
  */
 export { lambderTestApp } from "./testing/LambderTestApp.js";
 export type { LambderTestApp, LambderTestAppOptions, LambderTestedInstance } from "./testing/LambderTestApp.js";
-export type { LambderTestVisitor, LambderTestVisitorOptions, LambderTestRequestInit } from "./testing/LambderTestVisitor.js";
+export type { LambderTestVisitor, LambderTestVisitorOptions, LambderTestRequestInit, LambderTestVisitorEndpoint, LambderTestVisitorGroupCalls } from "./testing/LambderTestVisitor.js";
 export { assertApiSuccess, assertApiFailure, assertApiRefusal } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export { lambderSessionStoreConformance } from "./testing/lambderSessionStoreConformance.js";
@@ -27,7 +27,13 @@ export { lambderRateLimiterConformance } from "./testing/lambderRateLimiterConfo
 export type { LambderRateLimiterConformanceOptions } from "./testing/lambderRateLimiterConformance.js";
 export { lambderOneShotSecretStoreConformance } from "./testing/lambderOneShotSecretStoreConformance.js";
 export type { LambderOneShotSecretStoreConformanceOptions } from "./testing/lambderOneShotSecretStoreConformance.js";
+export { lambderCacheConformance } from "./testing/lambderCacheConformance.js";
+export type { LambderCacheConformanceOptions } from "./testing/lambderCacheConformance.js";
+export { lambderCacheStorageConformance } from "./testing/lambderCacheStorageConformance.js";
+export type { LambderCacheStorageConformanceOptions } from "./testing/lambderCacheStorageConformance.js";
 export type { LambderConformanceRunner, LambderConformanceIt, LambderConformanceExpect, LambderConformanceAssertion, LambderConformanceSetup, } from "./testing/LambderConformanceRunner.js";
+export { bootLambdaPackage } from "./testing/bootLambdaPackage.js";
+export type { LambderPackageBootOptions, LambderPackageBootCall, LambderPackageBootResult, LambderPackageBootCallResult, LambderPackageBootMeasurements, } from "./testing/bootLambdaPackage.js";
 export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
 export { LambderMemoryRateLimiter } from "./stores/LambderMemoryRateLimiter.js";
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";

package/dist/testing.js

@@ -23,6 +23,11 @@ export { lambderSessionStoreConformance } from "./testing/lambderSessionStoreCon
 export { lambderIdempotencyStoreConformance } from "./testing/lambderIdempotencyStoreConformance.js";
 export { lambderRateLimiterConformance } from "./testing/lambderRateLimiterConformance.js";
 export { lambderOneShotSecretStoreConformance } from "./testing/lambderOneShotSecretStoreConformance.js";
+export { lambderCacheConformance } from "./testing/lambderCacheConformance.js";
+export { lambderCacheStorageConformance } from "./testing/lambderCacheStorageConformance.js";
+// A built deployment package booted as Lambda boots it, in a fresh process,
+// for the check between packaging and deploying.
+export { bootLambdaPackage } from "./testing/bootLambdaPackage.js";
 // What a test reaches for beside the test app: the stores to inspect or to
 // hand it, a file source over fixtures, the refusal codes to assert on, and
 // the types of what a visitor and its session hand back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "14.1.1",
+  "version": "15.0.2",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [
@@ -113,7 +113,6 @@
     "@aws-sdk/client-dynamodb": "^3.868.0",
     "@aws-sdk/client-lambda": "^3.574.0",
     "@aws-sdk/client-s3": "^3.574.0",
-    "@aws-sdk/lib-dynamodb": "^3.574.0",
     "@aws-sdk/s3-presigned-post": "^3.574.0",
     "@aws-sdk/s3-request-presigner": "^3.574.0",
     "msw": "^2.0.0",
@@ -130,9 +129,6 @@
     "@aws-sdk/client-s3": {
       "optional": true
     },
-    "@aws-sdk/lib-dynamodb": {
-      "optional": true
-    },
     "@aws-sdk/s3-presigned-post": {
       "optional": true
     },
@@ -150,7 +146,6 @@
     "@aws-sdk/client-dynamodb": "^3.913.0",
     "@aws-sdk/client-lambda": "^3.1131.0",
     "@aws-sdk/client-s3": "^3.1127.0",
-    "@aws-sdk/lib-dynamodb": "^3.913.0",
     "@aws-sdk/s3-presigned-post": "^3.1141.0",
     "@aws-sdk/s3-request-presigner": "^3.1141.0",
     "@types/js-cookie": "^3.0.6",

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

@@ -1,20 +0,0 @@
-/**
- * Bounding the caller-supplied field of a tracker or scope key.
- *
- * The rate-limit engine and the idempotency engine each build a store key
- * around a field only the caller controls: a custom rate-limit key or a
- * session key, a callerIdentity or a session key. A store has a key limit of
- * its own (a DynamoDB partition key stops at 2048 bytes) and refuses a key
- * past it by throwing, and both engines fail open on a store throw by
- * default: a long enough field (a 3,000-character email, a device token)
- * would turn the rate limit or the idempotency off for that caller, in
- * silence, while the table held the field in plain text. So the field is
- * bounded before any store sees it, in one implementation the two engines
- * share, so they cannot drift apart.
- */
-/**
- * The field bounded: `<kind>:<value>` while the value fits, `<kind>:h:<sha256
- * hex>` once it does not. The digest keeps distinct callers on distinct
- * counters and scopes, and a value that fits stays readable in the table.
- */
-export declare const boundKeyField: (kind: string, value: string) => Promise<string>;

package/dist/shared/util/boundKeyField.js

@@ -1,34 +0,0 @@
-/**
- * Bounding the caller-supplied field of a tracker or scope key.
- *
- * The rate-limit engine and the idempotency engine each build a store key
- * around a field only the caller controls: a custom rate-limit key or a
- * session key, a callerIdentity or a session key. A store has a key limit of
- * its own (a DynamoDB partition key stops at 2048 bytes) and refuses a key
- * past it by throwing, and both engines fail open on a store throw by
- * default: a long enough field (a 3,000-character email, a device token)
- * would turn the rate limit or the idempotency off for that caller, in
- * silence, while the table held the field in plain text. So the field is
- * bounded before any store sees it, in one implementation the two engines
- * share, so they cannot drift apart.
- */
-import { joinKeyFields } from "./joinKeyFields.js";
-import { sha256HexOf } from "./LambderTextDigest.js";
-/**
- * The ceiling, in UTF-8 bytes, on the field as it is written into the key;
- * past it, the field is replaced by its digest. Measured escaped, since
- * joinKeyFields doubles every separator and escape character: a field of
- * 1,000 separators is 2,000 bytes in the key. 1024 sits well inside every
- * store's key limit, with the store's prefix and the engine's other fields
- * (API and policy names, a posted idempotency key of at most 200 characters)
- * joined around it.
- */
-const MAX_KEY_FIELD_BYTES = 1024;
-/**
- * The field bounded: `<kind>:<value>` while the value fits, `<kind>:h:<sha256
- * hex>` once it does not. The digest keeps distinct callers on distinct
- * counters and scopes, and a value that fits stays readable in the table.
- */
-export const boundKeyField = async (kind, value) => new TextEncoder().encode(joinKeyFields(value)).length > MAX_KEY_FIELD_BYTES
-    ? `${kind}:h:${await sha256HexOf(value)}`
-    : `${kind}:${value}`;