lambder 4.7.3 → 4.8.1

package/Readme.md

@@ -2,6 +2,11 @@
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
+**New in 4.8:**
+
+- **Grouped cache keys**: `LambderDdbCache` keys may be a `{ pk, sk }` pair instead of a string, which stores related entries in one partition: `{ pk: "division:ist-34", sk: "1700:1800" }` keeps every cached window of one division together. `deletePartition(pk)` then drops the whole group without knowing which sort keys exist, and `listSortKeys(pk, { prefix, limit })` reads back what is currently cached under it. The group invalidation a cache of derived, per-entity values needs, in place of remembering every key ever written or waiting out the TTL. Reads stay one request, and the memory layer, single-flight and fill lease stay per entry. Only the `pk` part is hashed, so the sort key is queryable; a caller's `#` is escaped rather than refused (`~`→`~0`, `#`→`~1`). Plain string keys keep their exact item layout, so a live table needs no migration and both forms can share a partition.
+- **`guards` on the API contract**: each contract entry now carries the `guards` option exactly as declared (`ApiContractType["getUser"]["guards"]` is the literal `{ readonly orgPermission: "USERS.MANAGE" }`), so a client-side map of what an API needs can be pinned to the server's own declaration with `satisfies` instead of a test that reads the server source.
+
 **New in 4.7:**
 
 - **Compressed request payloads**: `requestCompression` on `LambderCaller` gzips the payload of any call whose JSON reaches a threshold (`true` is `{ minBytes: 4096 }`), sending it as `payloadGz` beside its byte length instead of `payload` whenever that is actually smaller; the server restores it before rate-limit key slices, guards and input validation, so no call site, handler or schema changes. Chiefly a way to fit a large payload under Lambda's ~6MB invoke cap, which applies to the compressed bytes. The envelope stays `application/json` with its routing fields in plain text, so gateways, CDNs and mocks are unaffected. `maxRequestPayloadBytes` (default 20MB) bounds what a body may expand to.
@@ -175,6 +180,19 @@ export type ApiContractType = typeof lambder.ApiContract;
 export const handler = lambder.getHandler();
 ```
 
+Each contract entry carries the API's `input` and `output`, its `guardInputs` when a guardInput-mode guard applies, and its `guards` option exactly as declared (`ApiContractType["getUser"]["guards"]` is the literal `{ readonly orgPermission: "USERS.MANAGE" }`). A client that keeps its own map of what an API needs, to decide whether to render a screen before calling, pins that map to the declarations with `satisfies` instead of a test that reads the server source:
+
+```typescript
+type PermissionNeededBy<K extends keyof ApiContractType> =
+    ApiContractType[K] extends { guards: { orgPermission: infer N } } ? N : never;
+
+const NEEDS = {
+    getUser: "USERS.MANAGE",
+} as const satisfies { [K in keyof ApiContractType]?: PermissionNeededBy<K> };
+```
+
+Renaming the permission on the server, or moving the API to a different one, then fails the client's map to compile. Make the mapped type non-optional (over the guarded API names) when the map must also stay complete as guarded APIs are added.
+
 ### Adding Routes
 
 ```typescript
@@ -783,7 +801,7 @@ Also enforced at registration: **duplicate API names throw** (dispatch is first-
 
 ### DynamoDB Cache (LambderDdbCache)
 
-Standalone, persistent JSON cache backed by a DynamoDB table (`pk`/`sk` keys + `expiresAt` TTL attribute, same shape as the session table). Items are prefixed `CACHE#<namespace>#`, and the rate limiter (`RL#`) and idempotency store (`IDEM#`) prefix theirs too, so all three non-session systems can share one table without collisions; keep sessions in their own table for IAM scoping. Brotli-compressed values (the shared `compression` option), in-memory LRU layer, single-flight deduplication, a DynamoDB lease so only one Lambda fills a missing key, and fail-open semantics. Server-only. **Full guide with table setup: [docs/DDB_CACHE.md](./docs/DDB_CACHE.md).**
+Standalone, persistent JSON cache backed by a DynamoDB table (`pk`/`sk` keys + `expiresAt` TTL attribute, same shape as the session table). Items are prefixed `CACHE#<namespace>#`, and the rate limiter (`RL#`) and idempotency store (`IDEM#`) prefix theirs too, so all three non-session systems can share one table without collisions; keep sessions in their own table for IAM scoping. Brotli-compressed values (the shared `compression` option), in-memory LRU layer, single-flight deduplication, a DynamoDB lease so only one Lambda fills a missing key, fail-open semantics, and optional grouped keys for group invalidation. Server-only. **Full guide with table setup: [docs/DDB_CACHE.md](./docs/DDB_CACHE.md).**
 
 ```typescript
 import { LambderDdbCache } from "lambder";
@@ -799,6 +817,13 @@ const city = await cache.getOrSet(`city:${slug}`, async () => fetchCityFromDb(sl
     ttlSeconds: 7 * 24 * 3600,
 });
 // Also: cache.get(key), cache.set(key, value, { ttlSeconds }), cache.has(key), cache.delete(key)
+
+// A key can also be a { pk, sk } pair, which groups related entries under one
+// partition so the whole group can be invalidated without listing its members:
+const window = { pk: `division:${divisionId}`, sk: `${from}:${to}` };
+await cache.getOrSet(window, () => loadDivision(divisionId, from, to));
+await cache.deletePartition(`division:${divisionId}`);   // every cached window of it
+await cache.listSortKeys(`division:${divisionId}`);      // ["1700:1800", "1700:1900"]
 ```
 
 ### Typed Translations (createLambderI18n)

package/dist/core/Lambder.d.ts

@@ -288,7 +288,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    }, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
+    }, handler: (ctx: LambderRenderContext<z.infer<TInput>, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
     addSessionApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, true> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, true> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
@@ -299,7 +299,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
         idempotency?: _TIdempotencyEnabled extends true ? (boolean | {
             ttlSeconds?: number;
         }) : never;
-    } & LambderSessionGuardsField<_TSessionGuardsRequired, TGuardsOpt>, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
+    } & LambderSessionGuardsField<_TSessionGuardsRequired, TGuardsOpt>, handler: (ctx: LambderSessionRenderContext<z.infer<TInput>, TSessionData, Record<string, string>, LambderGuardDataOf<_TGuards, TGuardsOpt>>, resolver: LambderResolver<z.infer<TOutput>>) => MaybePromise<LambderResponse>): Lambder<TSessionData, MergeContract<_TContract, TName, z.infer<TInput>, z.infer<TOutput>, LambderGuardInputsOf<_TGuards, TGuardsOpt>, TGuardsOpt>, _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { compressText, restoreBoundedText, LambderCompressionError, LAMBDER_REST
 export type { LambderRestoreFailure } from "./shared/LambderCompressionCodec.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
-export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
+export type { LambderCacheKey, LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, LambderDdbCacheListOptions, } from "./stores/LambderDdbCache.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
 export type { LambderDdbRateLimiterOptions, LambderRateLimitWindow, LambderRateLimitPolicy, LambderRateLimitExceeded, LambderRateLimitResult, } from "./stores/LambderDdbRateLimiter.js";
 export { LambderDdbIdempotency } from "./stores/LambderDdbIdempotency.js";

package/dist/shared/LambderApiContract.d.ts

@@ -11,6 +11,13 @@ export type ApiContractShape = Record<string, {
     output: any;
     /** Present when the API declares guardInput-mode guards: guard name -> value the client must send via options.guardInputs. */
     guardInputs?: any;
+    /**
+     * Present when the API declares guards: the `guards` option exactly as
+     * written at registration, so a client-side copy of "what does this API
+     * need" can be pinned to the server's own declaration with `satisfies`
+     * rather than kept honest by a test that reads the source.
+     */
+    guards?: any;
 }>;
 /** Envelope flags/channels the server may set beside (or instead of) the payload. */
 export type LambderApiResponseConfig = {
@@ -29,13 +36,13 @@ export type LambderApiResponse<T> = LambderApiResponseConfig & {
 /**
  * Helper type for merging new API into existing contract during chaining
  */
-export type MergeContract<Old, Name extends string, In, Out, GuardInputs = never> = Old & {
-    [K in Name]: [GuardInputs] extends [never] ? {
-        input: In;
-        output: Out;
-    } : {
+export type MergeContract<Old, Name extends string, In, Out, GuardInputs = never, Guards = never> = Old & {
+    [K in Name]: ([GuardInputs] extends [never] ? {} : {
+        guardInputs: GuardInputs;
+    }) & ([Guards] extends [never] ? {} : {
+        guards: Guards;
+    }) & {
         input: In;
         output: Out;
-        guardInputs: GuardInputs;
     };
 };

package/dist/stores/LambderDdbCache.d.ts

@@ -19,6 +19,18 @@ export interface LambderDdbCacheOptions {
     memoryMaxBytes?: number;
     client?: DynamoDBClient;
 }
+/**
+ * Where a value lives. A plain string addresses one entry, as it always has.
+ * `{ pk, sk }` puts the entry in a partition it can share with others, so a
+ * group can be listed or dropped in one call: `{ pk: "division:ist-34", sk:
+ * "1700:1800" }` keeps every cached window of one division together.
+ * Only the `pk` part is hashed into the DynamoDB partition key; the sort key
+ * is stored readable, which is what makes prefix queries possible.
+ */
+export type LambderCacheKey = string | {
+    pk: string;
+    sk: string;
+};
 export interface LambderDdbCacheSetOptions {
     ttlSeconds?: number;
 }
@@ -26,6 +38,12 @@ export interface LambderDdbCacheGetOrSetOptions extends LambderDdbCacheSetOption
     leaseSeconds?: number;
     waitForFillMs?: number;
 }
+export interface LambderDdbCacheListOptions {
+    /** Only sort keys starting with this raw (unescaped) prefix. */
+    prefix?: string;
+    /** Cap on RESULTS, not on items read: the partition (or prefix range) is read either way. */
+    limit?: number;
+}
 /**
  * Persistent JSON cache backed by DynamoDB.
  *
@@ -42,6 +60,13 @@ export interface LambderDdbCacheGetOrSetOptions extends LambderDdbCacheSetOption
  * `expiresAt`. Items are prefixed `CACHE#<namespace>#` by default, so the
  * table can be shared with LambderDdbRateLimiter (`RL#`) and
  * LambderDdbIdempotency (`IDEM#`) without key collisions.
+ *
+ * A key may also be a `{ pk, sk }` pair, which groups entries under one
+ * partition so `deletePartition` and `listSortKeys` can work on the group
+ * without knowing its members. Plain-string keys keep the exact item layout
+ * they have always had (`meta`, `lock`, `chunk#...`), and grouped entries
+ * live beside them under `sk#<encoded sort key>#...`, so both forms can
+ * share a partition and a live table needs no migration.
  */
 export declare class LambderDdbCache {
     readonly tableName: string;
@@ -55,11 +80,28 @@ export declare class LambderDdbCache {
     private readonly memory;
     private readonly inFlight;
     constructor(options: LambderDdbCacheOptions);
-    get<T>(key: string): Promise<T | undefined>;
-    has(key: string): Promise<boolean>;
-    set<T>(key: string, value: T, options?: LambderDdbCacheSetOptions): Promise<void>;
-    delete(key: string): Promise<boolean>;
-    getOrSet<T>(key: string, factory: () => Promise<T>, options?: LambderDdbCacheGetOrSetOptions): Promise<T>;
+    get<T>(key: LambderCacheKey): Promise<T | undefined>;
+    private getByAddress;
+    has(key: LambderCacheKey): Promise<boolean>;
+    set<T>(key: LambderCacheKey, value: T, options?: LambderDdbCacheSetOptions): Promise<void>;
+    private setByAddress;
+    delete(key: LambderCacheKey): Promise<boolean>;
+    /**
+     * Drop every entry stored under one `pk`, without knowing which sort keys
+     * exist: the invalidation a group of related entries is worth grouping
+     * for. Returns the number of entries removed. In-memory copies held by
+     * OTHER Lambda containers still serve until their own TTL, as they do
+     * after a single-entry delete.
+     */
+    deletePartition(partition: string): Promise<number>;
+    /**
+     * The live (unexpired) sort keys stored under one `pk`, in table order.
+     * Plain-string entries have no sort key, so they never appear here.
+     * Reading a partition whose values are chunked also reads those chunk
+     * items, so grouping very large values makes listing more expensive.
+     */
+    listSortKeys(partition: string, options?: LambderDdbCacheListOptions): Promise<string[]>;
+    getOrSet<T>(key: LambderCacheKey, factory: () => Promise<T>, options?: LambderDdbCacheGetOrSetOptions): Promise<T>;
     /**
      * Cache infrastructure is best-effort for getOrSet: read, lease, or write
      * failures return the loader value. Loader failures still propagate and the
@@ -71,14 +113,32 @@ export declare class LambderDdbCache {
     private releaseLease;
     private readManifest;
     private readChunks;
+    /** Every item matching a partition (optionally a sort-key prefix), following pagination. */
+    private queryItems;
+    private deleteItems;
     private invalidateManifest;
     private batchWrite;
     /** The JSON text of a stored payload. */
     private decode;
     private remember;
     private normalizeKey;
+    private normalizePartition;
+    /** Length-prefixed so a partition ending in the separator cannot collide with a sort key. */
+    private memoryKeyOf;
     private partitionKey;
+    /**
+     * One of an entry's item keys. A plain-string entry keeps the bare
+     * suffix it has always used; a grouped one nests under its escaped sort
+     * key, whose trailing `#` is an unambiguous boundary because an escaped
+     * sort key never contains a bare `#`.
+     */
+    private itemSortKey;
+    /** The prefix covering every item of a grouped entry; null for a plain-string entry, which owns the bare item keys instead. */
+    private entryItemPrefix;
+    private isManifestSortKey;
     private chunkSortKey;
+    /** Drop every in-memory copy belonging to one partition. */
+    private forgetPartition;
     private nowSeconds;
     private isConditionalFailure;
 }

package/dist/stores/LambderDdbCache.js

@@ -10,10 +10,26 @@ const DEFAULT_MAX_VALUE_BYTES = 32 * 1024 * 1024;
 const DEFAULT_MEMORY_BYTES = 16 * 1024 * 1024;
 const META_SORT_KEY = "meta";
 const LOCK_SORT_KEY = "lock";
+const CHUNK_SORT_KEY_PREFIX = "chunk#";
+/** Item-key prefix that separates entries addressed with a sort key from plain-key entries sharing the partition. */
+const SORT_KEY_MARKER = "sk#";
+/** Budget for one encoded sort key, leaving room for the marker and the longest item suffix inside DynamoDB's 1024-byte range key limit. */
+const MAX_SORT_KEY_BYTES = 900;
 const BATCH_WRITE_LIMIT = 25;
 const MAX_BATCH_RETRIES = 8;
 /** Every value compressed by default; see the `compression` option. */
 const COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
+/**
+ * `#` separates the store's own item-key segments, so a caller's `#` is
+ * escaped rather than refused: `~` becomes `~0` and `#` becomes `~1`. An
+ * encoded sort key therefore never contains a bare `#`, which keeps
+ * `<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.
+ */
+const encodeSortKey = (value) => value.replace(/~/g, "~0").replace(/#/g, "~1");
+const decodeSortKey = (value) => value.replace(/~([01])/g, (_match, code) => code === "0" ? "~" : "#");
 // Node builtins are loaded lazily through node-polyfills so this module can
 // sit in a frontend bundle's import graph (via the package root) without
 // breaking; using the cache at runtime still requires Node. Brotli helpers
@@ -56,6 +72,13 @@ const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, mil
  * `expiresAt`. Items are prefixed `CACHE#<namespace>#` by default, so the
  * table can be shared with LambderDdbRateLimiter (`RL#`) and
  * LambderDdbIdempotency (`IDEM#`) without key collisions.
+ *
+ * A key may also be a `{ pk, sk }` pair, which groups entries under one
+ * partition so `deletePartition` and `listSortKeys` can work on the group
+ * without knowing its members. Plain-string keys keep the exact item layout
+ * they have always had (`meta`, `lock`, `chunk#...`), and grouped entries
+ * live beside them under `sk#<encoded sort key>#...`, so both forms can
+ * share a partition and a live table needs no migration.
  */
 export class LambderDdbCache {
     tableName;
@@ -94,8 +117,10 @@ export class LambderDdbCache {
         this.client = options.client ?? new DynamoDBClient({ region: options.region ?? "us-east-1" });
     }
     async get(key) {
-        const normalizedKey = this.normalizeKey(key);
-        const cached = this.memory?.get(normalizedKey);
+        return await this.getByAddress(this.normalizeKey(key));
+    }
+    async getByAddress(address) {
+        const cached = this.memory?.get(address.memoryKey);
         const nowSeconds = this.nowSeconds();
         if (cached && cached.expiresAt > nowSeconds) {
             try {
@@ -106,13 +131,13 @@ export class LambderDdbCache {
             }
         }
         if (cached)
-            this.memory?.delete(normalizedKey);
-        const pk = await this.partitionKey(normalizedKey);
-        const manifest = await this.readManifest(pk);
+            this.memory?.delete(address.memoryKey);
+        const pk = await this.partitionKey(address.partition);
+        const manifest = await this.readManifest(pk, address);
         if (!manifest || manifest.expiresAt <= nowSeconds)
             return undefined;
         try {
-            const stored = manifest.inlineData ?? await this.readChunks(pk, manifest);
+            const stored = manifest.inlineData ?? await this.readChunks(pk, address, manifest);
             if (stored.length !== manifest.storedBytes) {
                 throw new Error("stored byte length does not match manifest");
             }
@@ -121,28 +146,30 @@ export class LambderDdbCache {
             }
             const json = await this.decode(stored, manifest.encoding, manifest.uncompressedBytes);
             const parsed = JSON.parse(json);
-            this.remember(normalizedKey, stored, manifest.encoding, manifest.uncompressedBytes, manifest.expiresAt);
+            this.remember(address.memoryKey, stored, manifest.encoding, manifest.uncompressedBytes, manifest.expiresAt);
             return parsed;
         }
         catch (error) {
-            await this.invalidateManifest(pk, manifest.version);
+            await this.invalidateManifest(pk, address, manifest.version);
             console.warn(`Ignoring corrupt DynamoDB cache entry in ${this.namespace}`, error);
             return undefined;
         }
     }
     async has(key) {
-        const normalizedKey = this.normalizeKey(key);
-        const cached = this.memory?.get(normalizedKey);
+        const address = this.normalizeKey(key);
+        const cached = this.memory?.get(address.memoryKey);
         const nowSeconds = this.nowSeconds();
         if (cached?.expiresAt && cached.expiresAt > nowSeconds)
             return true;
         if (cached)
-            this.memory?.delete(normalizedKey);
-        const manifest = await this.readManifest(await this.partitionKey(normalizedKey));
+            this.memory?.delete(address.memoryKey);
+        const manifest = await this.readManifest(await this.partitionKey(address.partition), address);
         return !!manifest && manifest.expiresAt > nowSeconds;
     }
     async set(key, value, options = {}) {
-        const normalizedKey = this.normalizeKey(key);
+        return await this.setByAddress(this.normalizeKey(key), value, options);
+    }
+    async setByAddress(address, value, options) {
         const ttlSeconds = positiveInteger(options.ttlSeconds ?? this.defaultTtlSeconds, "ttlSeconds");
         const json = JSON.stringify(value);
         if (json === undefined)
@@ -157,7 +184,7 @@ export class LambderDdbCache {
         if (stored.length > this.maxValueBytes) {
             throw new Error(`Stored cache value exceeds maxValueBytes (${stored.length} > ${this.maxValueBytes})`);
         }
-        const pk = await this.partitionKey(normalizedKey);
+        const pk = await this.partitionKey(address.partition);
         const version = `${Date.now().toString(36)}-${await randomUUID()}`;
         const expiresAt = this.nowSeconds() + ttlSeconds;
         const chunks = [];
@@ -171,7 +198,7 @@ export class LambderDdbCache {
             PutRequest: {
                 Item: {
                     pk: { S: pk },
-                    sk: { S: this.chunkSortKey(version, index) },
+                    sk: { S: this.chunkSortKey(address, version, index) },
                     data: { B: chunk },
                     expiresAt: { N: String(expiresAt) },
                 },
@@ -182,7 +209,7 @@ export class LambderDdbCache {
             TableName: this.tableName,
             Item: {
                 pk: { S: pk },
-                sk: { S: META_SORT_KEY },
+                sk: { S: this.itemSortKey(address, META_SORT_KEY) },
                 version: { S: version },
                 chunkCount: { N: String(chunks.length) },
                 storedBytes: { N: String(stored.length) },
@@ -194,41 +221,70 @@ export class LambderDdbCache {
                 ...(inline ? { data: { B: stored } } : {}),
             },
         }));
-        this.remember(normalizedKey, stored, encoding, input.length, expiresAt);
+        this.remember(address.memoryKey, stored, encoding, input.length, expiresAt);
     }
     async delete(key) {
-        const normalizedKey = this.normalizeKey(key);
-        const pk = await this.partitionKey(normalizedKey);
-        this.memory?.delete(normalizedKey);
-        const keys = [];
-        let cursor;
-        do {
-            const response = await this.client.send(new QueryCommand({
-                TableName: this.tableName,
-                KeyConditionExpression: "#pk = :pk",
-                ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk" },
-                ExpressionAttributeValues: { ":pk": { S: pk } },
-                ProjectionExpression: "#pk, #sk",
-                ExclusiveStartKey: cursor,
-            }));
-            for (const item of response.Items ?? []) {
-                if (item.pk && item.sk)
-                    keys.push({ pk: item.pk, sk: item.sk });
-            }
-            cursor = response.LastEvaluatedKey;
-        } while (cursor);
-        await this.batchWrite(keys.map((Key) => ({ DeleteRequest: { Key } })));
-        return keys.length > 0;
+        const address = this.normalizeKey(key);
+        const pk = await this.partitionKey(address.partition);
+        this.memory?.delete(address.memoryKey);
+        // A grouped entry owns one contiguous item range; a plain-string one
+        // owns the bare item keys, so it must leave any grouped entries
+        // sharing its partition alone.
+        const prefix = this.entryItemPrefix(address);
+        const items = await this.queryItems(pk, { prefix, projection: "#pk, #sk" });
+        const owned = prefix ? items : items.filter((item) => !item.sk?.S?.startsWith(SORT_KEY_MARKER));
+        await this.deleteItems(owned);
+        return owned.length > 0;
+    }
+    /**
+     * Drop every entry stored under one `pk`, without knowing which sort keys
+     * exist: the invalidation a group of related entries is worth grouping
+     * for. Returns the number of entries removed. In-memory copies held by
+     * OTHER Lambda containers still serve until their own TTL, as they do
+     * after a single-entry delete.
+     */
+    async deletePartition(partition) {
+        const normalized = this.normalizePartition(partition);
+        const pk = await this.partitionKey(normalized);
+        this.forgetPartition(normalized);
+        const items = await this.queryItems(pk, { projection: "#pk, #sk" });
+        await this.deleteItems(items);
+        return items.filter((item) => this.isManifestSortKey(item.sk?.S)).length;
+    }
+    /**
+     * The live (unexpired) sort keys stored under one `pk`, in table order.
+     * Plain-string entries have no sort key, so they never appear here.
+     * Reading a partition whose values are chunked also reads those chunk
+     * items, so grouping very large values makes listing more expensive.
+     */
+    async listSortKeys(partition, options = {}) {
+        const pk = await this.partitionKey(this.normalizePartition(partition));
+        const prefix = `${SORT_KEY_MARKER}${encodeSortKey(options.prefix ?? "")}`;
+        const limit = options.limit === undefined ? undefined : positiveInteger(options.limit, "limit");
+        const nowSeconds = this.nowSeconds();
+        const items = await this.queryItems(pk, { prefix, projection: "#sk, #expiresAt", extraNames: { "#expiresAt": "expiresAt" } });
+        const sortKeys = [];
+        for (const item of items) {
+            const sk = item.sk?.S;
+            if (!sk || !this.isManifestSortKey(sk))
+                continue;
+            if (Number(item.expiresAt?.N) <= nowSeconds)
+                continue;
+            sortKeys.push(decodeSortKey(sk.slice(SORT_KEY_MARKER.length, -(META_SORT_KEY.length + 1))));
+            if (limit !== undefined && sortKeys.length >= limit)
+                break;
+        }
+        return sortKeys;
     }
     async getOrSet(key, factory, options = {}) {
-        const normalizedKey = this.normalizeKey(key);
-        const current = this.inFlight.get(normalizedKey);
+        const address = this.normalizeKey(key);
+        const current = this.inFlight.get(address.memoryKey);
         if (current)
             return current;
-        const fill = this.getOrSetFailOpen(normalizedKey, factory, options).finally(() => {
-            this.inFlight.delete(normalizedKey);
+        const fill = this.getOrSetFailOpen(address, factory, options).finally(() => {
+            this.inFlight.delete(address.memoryKey);
         });
-        this.inFlight.set(normalizedKey, fill);
+        this.inFlight.set(address.memoryKey, fill);
         return fill;
     }
     /**
@@ -236,7 +292,7 @@ export class LambderDdbCache {
      * failures return the loader value. Loader failures still propagate and the
      * loader is never repeated after it has completed successfully.
      */
-    async getOrSetFailOpen(key, factory, options) {
+    async getOrSetFailOpen(address, factory, options) {
         let factoryStarted = false;
         let factoryCompleted = false;
         let factoryValue;
@@ -247,64 +303,64 @@ export class LambderDdbCache {
             return factoryValue;
         };
         try {
-            const existing = await this.get(key);
+            const existing = await this.getByAddress(address);
             if (existing !== undefined)
                 return existing;
-            return await this.fill(key, trackedFactory, options);
+            return await this.fill(address, trackedFactory, options);
         }
         catch (error) {
             if (factoryStarted && !factoryCompleted)
                 throw error;
-            console.error(`DynamoDB cache failed open in ${this.namespace} for ${key}`, error);
+            console.error(`DynamoDB cache failed open in ${this.namespace} for ${address.memoryKey}`, error);
             if (factoryCompleted)
                 return factoryValue;
             return trackedFactory();
         }
     }
-    async fill(key, factory, options) {
+    async fill(address, factory, options) {
         const leaseSeconds = positiveInteger(options.leaseSeconds ?? 15, "leaseSeconds");
         const waitForFillMs = positiveInteger(options.waitForFillMs ?? 5_000, "waitForFillMs");
-        const pk = await this.partitionKey(key);
+        const pk = await this.partitionKey(address.partition);
         const owner = await randomUUID();
-        if (await this.acquireLease(pk, owner, leaseSeconds)) {
+        if (await this.acquireLease(pk, address, owner, leaseSeconds)) {
             try {
                 const value = await factory();
-                await this.set(key, value, { ttlSeconds: options.ttlSeconds });
+                await this.setByAddress(address, value, { ttlSeconds: options.ttlSeconds });
                 return value;
             }
             finally {
-                await this.releaseLease(pk, owner);
+                await this.releaseLease(pk, address, owner);
             }
         }
         const deadline = Date.now() + waitForFillMs;
         let delay = 50;
         while (Date.now() < deadline) {
             await sleep(delay + Math.floor(Math.random() * 25));
-            const value = await this.get(key);
+            const value = await this.getByAddress(address);
             if (value !== undefined)
                 return value;
-            if (await this.acquireLease(pk, owner, leaseSeconds)) {
+            if (await this.acquireLease(pk, address, owner, leaseSeconds)) {
                 try {
                     const loaded = await factory();
-                    await this.set(key, loaded, { ttlSeconds: options.ttlSeconds });
+                    await this.setByAddress(address, loaded, { ttlSeconds: options.ttlSeconds });
                     return loaded;
                 }
                 finally {
-                    await this.releaseLease(pk, owner);
+                    await this.releaseLease(pk, address, owner);
                 }
             }
             delay = Math.min(delay * 2, 500);
         }
         throw new Error(`Timed out waiting for DynamoDB cache fill in ${this.namespace}`);
     }
-    async acquireLease(pk, owner, leaseSeconds) {
+    async acquireLease(pk, address, owner, leaseSeconds) {
         const now = this.nowSeconds();
         try {
             await this.client.send(new PutItemCommand({
                 TableName: this.tableName,
                 Item: {
                     pk: { S: pk },
-                    sk: { S: LOCK_SORT_KEY },
+                    sk: { S: this.itemSortKey(address, LOCK_SORT_KEY) },
                     owner: { S: owner },
                     expiresAt: { N: String(now + leaseSeconds) },
                 },
@@ -320,11 +376,11 @@ export class LambderDdbCache {
             throw error;
         }
     }
-    async releaseLease(pk, owner) {
+    async releaseLease(pk, address, owner) {
         try {
             await this.client.send(new DeleteItemCommand({
                 TableName: this.tableName,
-                Key: { pk: { S: pk }, sk: { S: LOCK_SORT_KEY } },
+                Key: { pk: { S: pk }, sk: { S: this.itemSortKey(address, LOCK_SORT_KEY) } },
                 ConditionExpression: "#owner = :owner",
                 ExpressionAttributeNames: { "#owner": "owner" },
                 ExpressionAttributeValues: { ":owner": { S: owner } },
@@ -336,10 +392,10 @@ export class LambderDdbCache {
             }
         }
     }
-    async readManifest(pk) {
+    async readManifest(pk, address) {
         const response = await this.client.send(new GetItemCommand({
             TableName: this.tableName,
-            Key: { pk: { S: pk }, sk: { S: META_SORT_KEY } },
+            Key: { pk: { S: pk }, sk: { S: this.itemSortKey(address, META_SORT_KEY) } },
             ConsistentRead: false,
         }));
         const item = response.Item;
@@ -387,43 +443,60 @@ export class LambderDdbCache {
             inlineData,
         };
     }
-    async readChunks(pk, manifest) {
-        const prefix = `chunk#${manifest.version}#`;
-        const chunks = [];
-        let cursor;
-        do {
-            const response = await this.client.send(new QueryCommand({
-                TableName: this.tableName,
-                KeyConditionExpression: "#pk = :pk AND begins_with(#sk, :prefix)",
-                ExpressionAttributeValues: { ":pk": { S: pk }, ":prefix": { S: prefix } },
-                ProjectionExpression: "#sk, #data",
-                ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk", "#data": "data" },
-                ExclusiveStartKey: cursor,
-                ConsistentRead: false,
-            }));
-            for (const item of response.Items ?? []) {
-                if (item.sk?.S && item.data?.B) {
-                    chunks.push({ sk: item.sk.S, data: Buffer.from(item.data.B) });
-                }
-            }
-            cursor = response.LastEvaluatedKey;
-        } while (cursor);
+    async readChunks(pk, address, manifest) {
+        const prefix = this.itemSortKey(address, `${CHUNK_SORT_KEY_PREFIX}${manifest.version}#`);
+        const items = await this.queryItems(pk, {
+            prefix,
+            projection: "#sk, #data",
+            extraNames: { "#data": "data" },
+        });
+        const chunks = items
+            .filter((item) => item.sk?.S && item.data?.B)
+            .map((item) => ({ sk: item.sk.S, data: Buffer.from(item.data.B) }));
         chunks.sort((left, right) => left.sk.localeCompare(right.sk));
         if (chunks.length !== manifest.chunkCount) {
             throw new Error(`DynamoDB cache entry is missing chunks (${chunks.length}/${manifest.chunkCount})`);
         }
         for (let index = 0; index < chunks.length; index += 1) {
-            if (chunks[index]?.sk !== this.chunkSortKey(manifest.version, index)) {
+            if (chunks[index]?.sk !== this.chunkSortKey(address, manifest.version, index)) {
                 throw new Error(`DynamoDB cache entry has an invalid chunk index at ${index}`);
             }
         }
         return Buffer.concat(chunks.map((chunk) => chunk.data), manifest.storedBytes);
     }
-    async invalidateManifest(pk, version) {
+    /** Every item matching a partition (optionally a sort-key prefix), following pagination. */
+    async queryItems(pk, options) {
+        const items = [];
+        let cursor;
+        do {
+            const response = await this.client.send(new QueryCommand({
+                TableName: this.tableName,
+                KeyConditionExpression: options.prefix
+                    ? "#pk = :pk AND begins_with(#sk, :prefix)"
+                    : "#pk = :pk",
+                ExpressionAttributeNames: { "#pk": "pk", "#sk": "sk", ...options.extraNames },
+                ExpressionAttributeValues: {
+                    ":pk": { S: pk },
+                    ...(options.prefix ? { ":prefix": { S: options.prefix } } : {}),
+                },
+                ProjectionExpression: options.projection,
+                ExclusiveStartKey: cursor,
+                ConsistentRead: false,
+            }));
+            items.push(...(response.Items ?? []));
+            cursor = response.LastEvaluatedKey;
+        } while (cursor);
+        return items;
+    }
+    async deleteItems(items) {
+        const keys = items.flatMap((item) => item.pk && item.sk ? [{ pk: item.pk, sk: item.sk }] : []);
+        await this.batchWrite(keys.map((Key) => ({ DeleteRequest: { Key } })));
+    }
+    async invalidateManifest(pk, address, version) {
         try {
             await this.client.send(new DeleteItemCommand({
                 TableName: this.tableName,
-                Key: { pk: { S: pk }, sk: { S: META_SORT_KEY } },
+                Key: { pk: { S: pk }, sk: { S: this.itemSortKey(address, META_SORT_KEY) } },
                 ConditionExpression: "#version = :version",
                 ExpressionAttributeNames: { "#version": "version" },
                 ExpressionAttributeValues: { ":version": { S: version } },
@@ -464,6 +537,23 @@ export class LambderDdbCache {
         this.memory.set(key, { stored, encoding, uncompressedBytes, expiresAt }, { ttl });
     }
     normalizeKey(key) {
+        if (typeof key === "string") {
+            const partition = this.normalizePartition(key);
+            return { partition, sortKey: null, memoryKey: this.memoryKeyOf(partition, null) };
+        }
+        if (!key || typeof key !== "object")
+            throw new Error("Cache key is required");
+        const partition = this.normalizePartition(key.pk);
+        const sortKey = key.sk;
+        if (typeof sortKey !== "string" || !sortKey.trim())
+            throw new Error("Cache sort key is required");
+        const encodedBytes = Buffer.byteLength(encodeSortKey(sortKey), "utf8");
+        if (encodedBytes > MAX_SORT_KEY_BYTES) {
+            throw new Error(`Cache sort key must be at most ${MAX_SORT_KEY_BYTES} UTF-8 bytes once escaped (${encodedBytes})`);
+        }
+        return { partition, sortKey, memoryKey: this.memoryKeyOf(partition, sortKey) };
+    }
+    normalizePartition(key) {
         if (typeof key !== "string" || !key.trim())
             throw new Error("Cache key is required");
         if (Buffer.byteLength(key, "utf8") > 8 * 1024) {
@@ -471,11 +561,41 @@ export class LambderDdbCache {
         }
         return key;
     }
+    /** Length-prefixed so a partition ending in the separator cannot collide with a sort key. */
+    memoryKeyOf(partition, sortKey) {
+        return `${partition.length}:${partition}#${sortKey ?? ""}`;
+    }
     async partitionKey(key) {
         return `${this.keyPrefix}#${this.namespace}#${await sha256(key)}`;
     }
-    chunkSortKey(version, index) {
-        return `chunk#${version}#${String(index).padStart(6, "0")}`;
+    /**
+     * One of an entry's item keys. A plain-string entry keeps the bare
+     * suffix it has always used; a grouped one nests under its escaped sort
+     * key, whose trailing `#` is an unambiguous boundary because an escaped
+     * sort key never contains a bare `#`.
+     */
+    itemSortKey(address, suffix) {
+        return address.sortKey === null ? suffix : `${SORT_KEY_MARKER}${encodeSortKey(address.sortKey)}#${suffix}`;
+    }
+    /** The prefix covering every item of a grouped entry; null for a plain-string entry, which owns the bare item keys instead. */
+    entryItemPrefix(address) {
+        return address.sortKey === null ? null : `${SORT_KEY_MARKER}${encodeSortKey(address.sortKey)}#`;
+    }
+    isManifestSortKey(sk) {
+        return sk === META_SORT_KEY || (!!sk && sk.startsWith(SORT_KEY_MARKER) && sk.endsWith(`#${META_SORT_KEY}`));
+    }
+    chunkSortKey(address, version, index) {
+        return this.itemSortKey(address, `${CHUNK_SORT_KEY_PREFIX}${version}#${String(index).padStart(6, "0")}`);
+    }
+    /** Drop every in-memory copy belonging to one partition. */
+    forgetPartition(partition) {
+        if (!this.memory)
+            return;
+        const prefix = this.memoryKeyOf(partition, "");
+        for (const key of [...this.memory.keys()]) {
+            if (key.startsWith(prefix))
+                this.memory.delete(key);
+        }
     }
     nowSeconds() {
         return Math.floor(Date.now() / 1000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "4.7.3",
+  "version": "4.8.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",