lambder 4.7.3 → 4.9.1

package/Readme.md

@@ -2,6 +2,16 @@
 
 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.9:**
+
+- **Mandatory authorization on public APIs**: `requirePublicApiGuards: true` at creation makes `guards` a required field of every `addApi`, the same way `requireSessionApiGuards` does for session APIs, at the type level and at registration. Public APIs are open by default and that stays the default; what turning it on buys is that a public endpoint's openness becomes a written decision rather than an omission. The ones anybody may call declare a named no-op guard carrying the reason (`guards: { open: "Static strings already in the bundle." }`), the ones that authorize their caller some other way (a signature, a device secret, a one-shot token) name where that happens, and one grep over the guard names then lists every public door and why it is open. The two flags are independent, so an app can require either or both.
+- **An empty guards option is refused**: `guards: {}` and `guards: []` were inhabited by the option type and passed the require\*ApiGuards field check while normalizing to zero entries, so a declaration that authorized nothing satisfied a requirement that exists to make authorization explicit. Both are now compile errors (every form of the option is non-empty by construction) and a registration error for a plain-JS caller, whichever flag is on or off. Requiring the chosen key also rejects `guards: { theGuard: undefined }`, which an optional property accepted and which reached the guard's handler with an undefined param.
+
+**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 +185,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
@@ -711,7 +734,7 @@ lambder.addApi("public.resetPassword", {
     input: z.object({ email: z.string().email() }),
     output: z.object({ ok: z.boolean() }),
     rateLimit: ["authPerIp", "codePerEmail"],   // stacked: checked in order, first exceeded refuses (429 envelope + Retry-After)
-    guards: "captcha",                          // one name, a list of names, or a { name: param } map
+    guards: "captcha",                          // one name, a non-empty list of names, or a non-empty { name: param } map
 }, handler);
 
 lambder.addSessionApi("secure.order.create", {
@@ -748,6 +771,28 @@ const lambder = initLambder<SessionData>().create({
 lambder.addSessionApi("secure.order.create", { input, output, guards: { orgPermission: "ORDERS.CREATE" } }, handler);
 lambder.addSessionApi("secure.me.logOut", { input, output, guards: "sessionOnly" }, handler);
 lambder.addSessionApi("secure.report.list", { input, output }, handler);   // compile error: which guard?
+lambder.addSessionApi("secure.report.list", { input, output, guards: {} }, handler);   // compile error: {} declares no guard
+```
+
+**The same for public APIs (`requirePublicApiGuards`)**: public APIs are open by default, and that remains the default. An app whose public surface has grown past a handful of endpoints can turn `requirePublicApiGuards: true` on to make each one's openness a written decision instead of an omission. Not every public endpoint has a control that can be hoisted into a guard (an endpoint that checks a password *is* the check), so the vocabulary an app declares here is usually a real guard for what is a genuine precondition, plus named no-op guards for the rest. The two flags are independent; either or both may be on.
+
+```typescript
+const lambder = initLambder<SessionData>().create({
+    apiPath: "/api",
+    guards: {
+        deviceToken: lambderGuard({ apiInput: z.object({ deviceToken: z.string().min(20) }), handler: (_c, { deviceToken }) => requireDevice(deviceToken) }),
+        // Anyone may call, and the param records why: `grep "open:"` lists every public door.
+        open: lambderGuard({ handler: (_c, _p, _r, _reason: string) => {} }),
+        // This endpoint establishes identity; the proof is the handler's own work.
+        credentialFlow: lambderGuard({ handler: () => {} }),
+    },
+    requirePublicApiGuards: true,
+});
+
+lambder.addApi("public.device.report", { input, output, guards: "deviceToken" }, handler);
+lambder.addApi("public.translations", { input, output, guards: { open: "Static strings already in the bundle." } }, handler);
+lambder.addApi("public.login", { input, output, guards: "credentialFlow" }, handler);
+lambder.addApi("public.search", { input, output }, handler);   // compile error: open to anyone, or authorized how?
 ```
 
 For api modules split across files, DERIVE the annotation type from the real instance instead of writing it by hand: create the instance next to the policy declarations and export `typeof` it. The type can never drift from what actually runs, and modules import it without a cycle (the app file imports no modules):
@@ -783,7 +828,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 +844,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

@@ -21,7 +21,7 @@ type MaybePromise<T> = T | Promise<T>;
 type Path = `/${string}`;
 type ActionFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
 type SessionActionFunction<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => MaybePromise<LambderResponse>;
-type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any, any>) => void | Promise<void>;
+type HookCreatedFunction = (lambderInstance: Lambder<any, any, any, any, any, any, any>) => void | Promise<void>;
 /** Return the (possibly replaced) ctx to continue, a LambderResponse to short-circuit, or an Error to fail. */
 type HookBeforeRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderRenderContext | LambderResponse | Error>;
 type HookAfterRenderFunction = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResponse) => MaybePromise<LambderResponse | Error>;
@@ -157,19 +157,38 @@ export type LambderCreateOptions<TSessionData = any> = {
      * from. Default: false.
      */
     requireSessionApiGuards?: boolean;
+    /**
+     * The same for public APIs: every addApi must declare `guards`, at the
+     * type level and at registration.
+     *
+     * Public APIs are open by default and that is the right default, so this
+     * is off unless an app decides otherwise. What it buys an app that turns
+     * it on is that a public endpoint's openness becomes a written decision
+     * rather than an omission: the ones anybody may call declare a named no-op
+     * guard carrying the reason, and the ones that authorize their caller some
+     * other way (a signature, a device secret, a one-shot token) name where
+     * that happens. One grep over the guard names then lists every public
+     * door and why it is open, which is the review question a growing public
+     * surface makes expensive to answer any other way. Needs a guards map to
+     * pick from. Default: false.
+     */
+    requirePublicApiGuards?: boolean;
     /** Declarative idempotency: your store plus replay defaults; APIs opt in via `idempotency: true | { ttlSeconds }`. */
     idempotency?: LambderApiIdempotencyConfig;
 };
 /**
- * The `guards` field of a session API's options: optional by default,
- * required once create() received requireSessionApiGuards, so that an
- * authorization declaration cannot be forgotten at the type level.
+ * The `guards` field of an API's options: optional by default, required once
+ * create() received the require*ApiGuards flag for that kind of API, so that
+ * an authorization declaration cannot be forgotten at the type level.
+ *
+ * One type for both kinds: the requirement is the same shape either way, and
+ * only which flag switches it on differs.
  */
-type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
-    /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Required on this instance (requireSessionApiGuards): an API the session alone authorizes declares the named no-op session guard. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
+type LambderRequirableGuardsField<TRequired extends boolean, TGuardsOpt> = TRequired extends true ? {
+    /** Named guards, run in declared order before input validation: a name, a non-empty list of names, or a non-empty { name: param } map for parameterized guards. Required on this instance: an API that needs no authorization declares a named no-op guard, so every opt-out is explicit and one grep lists them all. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
     guards: TGuardsOpt;
 } : {
-    /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
+    /** Named guards, run in declared order before input validation: a name, a non-empty list of names, or a non-empty { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
     guards?: TGuardsOpt;
 };
 /**
@@ -184,6 +203,7 @@ type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequire
  * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
+ * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
  *
  * @example
  * ```typescript
@@ -194,7 +214,7 @@ type LambderSessionGuardsField<TRequired extends boolean, TGuardsOpt> = TRequire
  *   .addApi('createUser', { input: z.object({...}), output: z.object({...}) }, handler);
  * ```
  */
-export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false> {
+export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false, _TSessionGuardsRequired extends boolean = false, _TPublicGuardsRequired extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
     /** The instance's file reader (source + caches), or null without the files option. */
@@ -228,6 +248,7 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     private finalizeOptions;
     private maxRequestPayloadBytes;
     private requireSessionApiGuards;
+    private requirePublicApiGuards;
     private lambderSessionManager?;
     private sessionCookieOptions;
     private sessionTokenCookieKey;
@@ -275,20 +296,18 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     addRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: ActionFunction): this;
     addSessionRoute<TPath extends Path>(condition: TPath, actionFn: (ctx: LambderSessionRenderContext<any, TSessionData, PathParamsOf<TPath>>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
     addSessionRoute(condition: RegExp | ConditionFunction | LambderRouteMatcher, actionFn: SessionActionFunction<TSessionData>): this;
-    use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired>;
+    use<_TNewContract extends Record<string, any>>(plugin: (lambder: Lambder<TSessionData, _TContract, any, any, any, any, any>) => Lambder<TSessionData, _TNewContract, any, any, any, any, any>): Lambder<TSessionData, _TNewContract extends _TContract ? _TNewContract : (_TContract & _TNewContract), _TRateLimitPolicies, _TGuards, _TIdempotencyEnabled, _TSessionGuardsRequired, _TPublicGuardsRequired>;
     addApi<TName extends string, TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, const TRateOpt extends LambderRateLimitOption<_TRateLimitPolicies, z.infer<TInput>, false> = never, const TGuardsOpt extends LambderGuardsOption<_TGuards, z.infer<TInput>, false> = never>(name: TName, schema: {
         input: TInput;
         output: TOutput;
     } & {
         /** Named rate limits, checked in declared order before guards and validation: a name, a list of names, or a { name: true | override } map (windows overridable on perApi budgets, errorMessage on any). The first exceeded one refuses (429 envelope + Retry-After); attempts count on every counter checked before it. */
         rateLimit?: TRateOpt;
-        /** Named guards, run in declared order before input validation: a name, a list of names, or a { name: param } map for parameterized guards. Their input requirements merge into this API's contract input; their return values land typed on ctx.guardData. */
-        guards?: TGuardsOpt;
         /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
         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>;
+    } & LambderRequirableGuardsField<_TPublicGuardsRequired, TGuardsOpt>, 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, _TPublicGuardsRequired>;
     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 +318,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>;
+    } & LambderRequirableGuardsField<_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, _TPublicGuardsRequired>;
     /**
      * Fetch the session or short-circuit the request: API calls get the
      * protocol's { sessionExpired: true } response (handled by LambderCaller),
@@ -382,5 +401,5 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
 export declare const initLambder: <TSessionData = any>() => {
     create<const TOptions extends LambderCreateOptions<TSessionData>>(options: TOptions): Lambder<TSessionData, {}, TOptions["rateLimits"] extends {
         policies: infer TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>;
-    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false, TOptions["requireSessionApiGuards"] extends true ? true : false>;
+    } ? TPolicies : {}, TOptions["guards"] extends Record<string, LambderApiGuard<any, any, any>> ? LambderGuardMetaMap<TOptions["guards"]> : {}, TOptions["idempotency"] extends LambderApiIdempotencyConfig ? true : false, TOptions["requireSessionApiGuards"] extends true ? true : false, TOptions["requirePublicApiGuards"] extends true ? true : false>;
 };

package/dist/core/Lambder.js

@@ -24,6 +24,7 @@ import { DEFAULT_MAX_REQUEST_PAYLOAD_BYTES } from "../shared/LambderRequestPaylo
  * @typeParam _TGuards - @internal Guard metadata map inferred from create()'s guards (do not pass manually)
  * @typeParam _TIdempotencyEnabled - @internal True when create() received idempotency (do not pass manually)
  * @typeParam _TSessionGuardsRequired - @internal True when create() received requireSessionApiGuards (do not pass manually)
+ * @typeParam _TPublicGuardsRequired - @internal True when create() received requirePublicApiGuards (do not pass manually)
  *
  * @example
  * ```typescript
@@ -68,6 +69,7 @@ export default class Lambder {
     finalizeOptions;
     maxRequestPayloadBytes;
     requireSessionApiGuards;
+    requirePublicApiGuards;
     lambderSessionManager;
     sessionCookieOptions = {};
     sessionTokenCookieKey = "LMDRSESSIONTKID";
@@ -116,8 +118,10 @@ export default class Lambder {
         if (options.idempotency)
             this.getOrCreatePolicyEngine().setIdempotency(options.idempotency);
         this.requireSessionApiGuards = options.requireSessionApiGuards ?? false;
-        if (this.requireSessionApiGuards && !options.guards) {
-            throw new Error("Lambder: requireSessionApiGuards needs a guards map at creation for session APIs to declare from.");
+        this.requirePublicApiGuards = options.requirePublicApiGuards ?? false;
+        const requireFlag = this.requireSessionApiGuards ? "requireSessionApiGuards" : "requirePublicApiGuards";
+        if ((this.requireSessionApiGuards || this.requirePublicApiGuards) && !options.guards) {
+            throw new Error(`Lambder: ${requireFlag} needs a guards map at creation for APIs to declare from.`);
         }
     }
     setRouteFallbackHandler(routeFallbackHandler) {
@@ -215,9 +219,13 @@ export default class Lambder {
             throw new Error(`Lambder: duplicate API name "${name}". Dispatch is first-match, so the second registration would be silently dead code.`);
         }
         this.registeredApiNames.add(name);
-        if (mode === "session" && this.requireSessionApiGuards && options.guards === undefined) {
-            throw new Error(`Lambder: session API "${name}" declares no guards, and requireSessionApiGuards is on. ` +
-                `Declare the guard that authorizes it, or the named no-op guard that marks the session itself as the whole authorization.`);
+        const guardsRequired = mode === "session" ? this.requireSessionApiGuards : this.requirePublicApiGuards;
+        if (guardsRequired && options.guards === undefined) {
+            const optOut = mode === "session"
+                ? "the named no-op guard that marks the session itself as the whole authorization"
+                : "the named no-op guard that records why anyone may call it";
+            throw new Error(`Lambder: ${mode} API "${name}" declares no guards, and require${mode === "session" ? "Session" : "Public"}ApiGuards is on. ` +
+                `Declare the guard that authorizes it, or ${optOut}.`);
         }
         const usesPolicies = options.rateLimit !== undefined || options.guards !== undefined || options.idempotency !== undefined;
         if (!usesPolicies)

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/policies/LambderApiGuards.d.ts

@@ -164,18 +164,42 @@ export type LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession extend
         param: undefined;
     } ? K & string : never;
 }[LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards];
-/**
- * The per-API `guards` option: one paramless guard name, an ordered list of
- * paramless names, or an object map that can carry each guard's param
- * (`true` enables a paramless guard). Map entries run in insertion order.
- */
-export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[] | {
+/** The map form's full shape: every declarable guard name, each carrying its own param type. */
+type LambderGuardsMap<TGuards, TPayload, TIncludeSession extends boolean> = {
     readonly [K in LambderAllowedGuardNames<TGuards, TPayload, TIncludeSession> & keyof TGuards]?: TGuards[K] extends {
         param: undefined;
     } ? true : TGuards[K] extends {
         param: infer P;
     } ? P : true;
 };
+/**
+ * The map form with AT LEAST ONE entry: the union, over every declarable
+ * name, of "this one required and the rest optional".
+ *
+ * An all-optional map is inhabited by `{}`, which would let `guards: {}`
+ * satisfy requireSessionApiGuards / requirePublicApiGuards at the type level
+ * while declaring no guard at all: the option is present, so the required-field
+ * check passes, and it normalizes to zero entries, so nothing runs. Requiring
+ * the chosen key also rejects `{ theGuard: undefined }`, which an optional
+ * property accepts and which would otherwise reach the guard's handler with an
+ * undefined param.
+ */
+type LambderNonEmptyGuardsMap<TGuards, TPayload, TIncludeSession extends boolean, TMap = LambderGuardsMap<TGuards, TPayload, TIncludeSession>> = {
+    [K in keyof TMap]-?: Required<Pick<TMap, K>> & Omit<TMap, K>;
+}[keyof TMap];
+/**
+ * The per-API `guards` option: one paramless guard name, a non-empty ordered
+ * list of paramless names, or a non-empty object map that can carry each
+ * guard's param (`true` enables a paramless guard). Map entries run in
+ * insertion order.
+ *
+ * Every form is non-empty by construction, so declaring the option is always
+ * declaring a guard. See LambderNonEmptyGuardsMap.
+ */
+export type LambderGuardsOption<TGuards, TPayload, TIncludeSession extends boolean> = LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession> | readonly [
+    LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>,
+    ...LambderParamlessGuardNames<TGuards, TPayload, TIncludeSession>[]
+] | LambderNonEmptyGuardsMap<TGuards, TPayload, TIncludeSession>;
 /**
  * The typed ctx.guardData an API's handler sees: declared guards that return
  * a value, keyed by name. Check-only (void) guards never appear.

package/dist/policies/LambderApiGuards.js

@@ -48,7 +48,18 @@ export class LambderApiGuardsEngine {
     }
     /** Startup validation of one API registration's guards option. */
     assertRegistration(apiName, mode, guardsOption) {
-        for (const { name } of toGuardEntries(guardsOption)) {
+        const entries = toGuardEntries(guardsOption);
+        // The runtime half of LambderNonEmptyGuardsMap. `guards: {}` and
+        // `guards: []` are present-but-empty: they satisfy the require*ApiGuards
+        // field check while running nothing, which is the one shape that turns a
+        // mandatory authorization declaration back into an optional one. The type
+        // rejects both; a plain-JS caller, a cast, or a spread that happened to
+        // produce an empty object lands here instead.
+        if (guardsOption !== undefined && entries.length === 0) {
+            throw new Error(`Lambder: API "${apiName}" declares an empty guards option, which authorizes nothing. ` +
+                `Name the guard that authorizes it, or omit the option entirely.`);
+        }
+        for (const { name } of entries) {
             const guardDef = this.guards[name];
             if (!guardDef) {
                 throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);

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.9.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",