lambder 4.2.1 → 4.3.1

package/Readme.md

@@ -2,12 +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.3:**
+
+- **Compressed sessions**: `session.data` is stored Brotli-compressed by default, as `dataBr` + `dataBytes` on the record, the same scheme LambderDdbCache and LambderDdbIdempotency use (one shared implementation). A session that caches roles, permissions or product lists shrinks 2-3x and stays within one DynamoDB read unit for longer. `session.compression` is `true` by default (the same as `{ minBytes: 0 }`: every record compressed); `false` turns it off and `{ minBytes }` compresses only from that JSON size. Records written under either setting read back, so it can be switched on or off on a live table.
+
 **New in 4.2:**
 
-- **Rate-limit budgets are explicit**: every policy declares `budget: "perApi"` (each referencing API gets its own counter, so the numbers are a per-API ceiling) or `budget: "perPolicy"` (one counter shared by every API referencing the policy). There is no default, so a declaration always says what its numbers span; the policy is the group, and two separate shared budgets are two policies.
+- **Rate-limit budgets**: a policy's `budget` is `"perApi"` (default: each referencing API gets its own counter, so the numbers are a per-API ceiling and three APIs on a 60/min policy allow one IP 180/min in total) or `"perPolicy"` (one counter shared by every API referencing the policy). The policy is the group, and two separate shared budgets are two policies.
 - **Per-API tuning**: the `rateLimit` option gained a map form like guards, `rateLimit: { lookupPerIp: { perMin: 20 } }`, which merges window overrides over a perApi policy's own (a tighter burst keeps the policy's daily cap). Overriding the windows of a perPolicy policy is a startup error; `errorMessage` is overridable on either.
 - **Retry-After**: a 429 carries the exceeded window's reset as a `Retry-After` header (CORS exposes it by default via the new `exposeHeaders` option), `LambderCaller` failure outcomes surface it as `retryAfterSeconds`, `LambderDdbRateLimiter.isRateLimited()` answers `false | { window, limit, resetAt }`, and `LambderApiError`/`refuse()` accept `headers`.
-- **One refusal shape**: every refusal the framework itself authors (rate limit 429, idempotency 409 and 400, unknown API) is a `LambderRefusalMessage` (`{ type, content }`), and a policy's `errorMessage` is typed as one, so an `errorMessageHandler` reading `.content` works everywhere.
+- **One refusal shape, with codes**: `LambderRefusalMessage` gained an optional machine-readable `code` (`refuse(content, { code })`), so clients branch and translate on an identifier instead of string-matching prose. Every refusal the framework itself authors (rate limit 429, idempotency 409 and 400, unknown API) is a `LambderRefusalMessage` stamped with a `LAMBDER_REFUSAL_CODES` constant under the reserved `lambder/` prefix; a rate-limit policy's own `errorMessage` (typed as a refusal message) inherits `lambder/rate-limited` unless it sets a code.
 - **One validation path**: preflight slices (guard `apiInput`/`guardInput`, rate-limit `apiInput` keys) answer through `setApiInputValidationErrorHandler` exactly like the API's own schema.
 
 **New in v4:**
@@ -302,6 +306,7 @@ const lambder = initLambder<SessionData>().create({
         tableRegion: "us-east-1",
         sessionSalt: "CHANGE-THIS-TO-A-SECURE-RANDOM-STRING",
         enableSlidingExpiration: true, // Optional: extend session on each access
+        compression: true,             // Optional: Brotli-compress session.data at rest (default true; false to disable, or { minBytes })
         // Optionally customize cookie names (defaults: LMDRSESSIONTKID, LMDRSESSIONCSTK)
         tokenCookieKey: "MY_SESSION_TOKEN",
         csrfCookieKey: "MY_CSRF_TOKEN",
@@ -353,6 +358,21 @@ Semantics:
 - Records created before `dataRefresh` was enabled renew on their first read.
 - `updateSessionData()` marks data fresh (it was just written deliberately); `regenerateSession()` carries the old freshness stamp over.
 
+#### Session data at rest (`compression`)
+
+`session.data` is stored Brotli-compressed by default: the record carries the data's JSON as Brotli bytes in `dataBr` beside its byte length in `dataBytes`, in place of a plain `data` attribute. It is the scheme `LambderDdbCache` and `LambderDdbIdempotency` already use, from one shared implementation, and the byte length both bounds the decompression and verifies it, so a truncated record fails to decode rather than decoding to something else. Session data that caches roles, permissions or product lists typically shrinks 2-3x, which keeps a growing session within one DynamoDB read unit (4KB for the consistent reads sessions use) and one write unit (1KB) for longer.
+
+```typescript
+session: {
+    // ...
+    compression: true, // default: every record compressed, the same as { minBytes: 0 }
+    // compression: { minBytes: 1024 } compresses only records whose JSON is 1KB+
+    // compression: false stores data as a plain attribute
+}
+```
+
+`quality` (Brotli 0-11, default 5) is also accepted. Reads accept both record shapes, so the setting can be switched on or off on a live table: records written under the other setting keep reading, and each is rewritten in the current shape on its next write (a sliding-expiration or `dataRefresh` write included). A compressed record that fails to decode is treated like any malformed record: no session.
+
 #### Session Controller
 
 Access the session controller with `lambder.getSessionController(ctx)`:
@@ -479,7 +499,7 @@ Responses are finalized once at the end of the request: automatic gzip (when the
 
 ### Typed API Refusals (refuse / LambderApiError)
 
-A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. The one-liner for the common case is `refuse()`: callable from anywhere in an API call's stack, it throws a typed refusal carrying the standard `LambderRefusalMessage` shape (`{ type, title?, content }`) that the pipeline maps onto the envelope's `errorMessage`, so refusals never pollute crash logging and clients get a parseable response:
+A refusal ("you are not allowed", "quota exceeded") is not a crash. `res.die.*` covers refusals where you hold the resolver, but shared helpers (permission checks, validators) usually don't. The one-liner for the common case is `refuse()`: callable from anywhere in an API call's stack, it throws a typed refusal carrying the standard `LambderRefusalMessage` shape (`{ type, code?, title?, content }`) that the pipeline maps onto the envelope's `errorMessage`, so refusals never pollute crash logging and clients get a parseable response:
 
 ```typescript
 import { refuse } from "lambder";
@@ -487,9 +507,12 @@ import { refuse } from "lambder";
 if (!row) refuse("Record not found.");                                  // { type: "warning", content }
 if (!isAdmin) refuse("Admins only.", { notAuthorized: true });          // + envelope flag
 refuse("Too many attempts.", { type: "error", statusCode: 429 });       // custom rendering intent + status
+if (exists) refuse("Already reported.", { code: "ALREADY_REPORTED" }); // + machine-readable identity
 // TypeScript applies never-return narrowing: after `if (!row) refuse(...)`, row is defined.
 ```
 
+`code` is the refusal's identity for machines: clients branch and translate on it (a translated client never displays `content`, it looks the code up), and `content` stays the human-readable fallback for codes a client does not know yet. Keep your app's codes as one typed vocabulary in shared code. The framework stamps the refusals it authors itself with `LAMBDER_REFUSAL_CODES` (exported from `lambder` and `lambder/client`) under the reserved `lambder/` prefix, so app codes never collide: `rateLimited`, `duplicateInFlight`, `invalidIdempotencyKey`, `apiNotFound`. A rate-limit policy's own `errorMessage` inherits `lambder/rate-limited` unless it sets a code, so an `errorMessageHandler` can treat every rate limit alike and still special-case the ones you name.
+
 For full control of the errorMessage payload (apps with their own message vocabulary), throw `LambderApiError` directly; `refuse()` is sugar over it:
 
 ```typescript
@@ -521,16 +544,16 @@ const lambder = initLambder<SessionData>().create({
     apiPath: "/api",
     // 1. Rate limiting: your limiter instance + named policies. Each policy
     //    declares its windows, what one counter tracks ("per"), and what one
-    //    budget spans ("budget", required so the numbers are never ambiguous):
-    //    "perApi" gives every referencing API its own counter (three APIs on a
-    //    60/min policy allow one IP 180/min in total), "perPolicy" makes every
-    //    referencing API share ONE counter. The policy IS the group: separate
-    //    shared budgets for, say, user APIs and report APIs are two policies.
+    //    budget spans ("budget"): "perApi" (default) gives every referencing
+    //    API its own counter, so three APIs on a 60/min policy allow one IP
+    //    180/min in total; "perPolicy" makes every referencing API share ONE
+    //    counter. The policy IS the group: separate shared budgets for, say,
+    //    user APIs and report APIs are two policies.
     rateLimits: {
         limiter: new LambderDdbRateLimiter({ tableName: "app-rate-limiter", region: "us-east-1", failOpen: true }),
         policies: {
-            authPerIp:    { perMin: 5, perHour: 30, per: "ip", budget: "perApi" },
-            writePerUser: { perMin: 30, per: "session", budget: "perApi" },   // only referable from addSessionApi (also enforced at compile time)
+            authPerIp:    { perMin: 5, perHour: 30, per: "ip" },
+            writePerUser: { perMin: 30, per: "session" },   // only referable from addSessionApi (also enforced at compile time)
             codePerEmail: {
                 perMin: 3,
                 // ONE combined budget across every API that references this

package/dist/client.d.ts

@@ -8,8 +8,8 @@
  */
 export { default as LambderCaller } from "./client/LambderCaller.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope, } from "./client/LambderCaller.js";
-export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
-export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./shared/LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export type { ApiContractShape, LambderApiResponse, LambderApiResponseConfig } from "./shared/LambderApiContract.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";

package/dist/client.js

@@ -10,7 +10,7 @@
 export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;
 // in the browser they are plain Errors).
-export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 // Type-safe templating (tagged templates with auto-escaping)
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml } from "./shared/LambderHtml.js";
 // Typed translations (standalone, isomorphic)

package/dist/core/Lambder.d.ts

@@ -5,7 +5,7 @@ import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, type LambderHttpResponse } from "./LambderResponse.js";
 import { type ConditionFunction, type LambderRouteMatcher, type PathParamsOf } from "./LambderRouting.js";
 import { type LambderCorsConfig } from "./LambderCors.js";
-import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
+import { type LambderSessionDataRefreshConfig, type LambderSessionCompressionConfig } from "../session/LambderSessionManager.js";
 import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../policies/LambderApiGuards.js";
@@ -88,6 +88,14 @@ export type LambderSessionOptions<TSessionData = any> = {
      * semantics.
      */
     dataRefresh?: LambderSessionDataRefreshConfig<TSessionData>;
+    /**
+     * Brotli compression of session.data at rest. `true` (the default)
+     * compresses every record, the same as `{ minBytes: 0 }`; `false` turns
+     * it off; `{ minBytes }` compresses only records whose JSON is at least
+     * that many bytes. Records written under either setting read back, so
+     * it can be switched on or off on a live table.
+     */
+    compression?: boolean | LambderSessionCompressionConfig;
 };
 /**
  * Everything an instance is configured with, in ONE declaration: base

package/dist/core/Lambder.js

@@ -6,7 +6,7 @@ import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
-import { isLambderApiError } from "../shared/LambderApiError.js";
+import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
 /**
@@ -90,6 +90,7 @@ export default class Lambder {
                 enableSlidingExpiration: session.enableSlidingExpiration,
                 slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
                 dataRefresh: session.dataRefresh,
+                compression: session.compression,
             });
             this.sessionCookieOptions = session.cookie ?? {};
             if (session.tokenCookieKey)
@@ -423,7 +424,7 @@ export default class Lambder {
         if (isAPI) {
             if (this.apiFallbackHandler)
                 return await this.apiFallbackHandler(ctx, resolver);
-            return resolver.api(null, { errorMessage: { type: "warning", content: "API not found." } });
+            return resolver.api(null, { errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.apiNotFound, content: "API not found." } });
         }
         if (this.publicFilesHandler) {
             const fileResponse = await this.publicFilesHandler.handle(ctx);

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
 export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
-export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
-export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefuseOptions } from "./shared/LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
+export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
 export { default as LambderResolver } from "./core/LambderResolver.js";
 export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
@@ -18,7 +18,7 @@ export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, Lamb
 export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
 export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
-export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
+export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig, LambderSessionCompressionConfig } from "./session/LambderSessionManager.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";

package/dist/index.js

@@ -3,7 +3,7 @@ export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiError, isLambderApiError, refuse } from "./shared/LambderApiError.js";
+export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
 export { default as LambderResolver } from "./core/LambderResolver.js";
 export { default as LambderSessionManager } from "./session/LambderSessionManager.js";

package/dist/policies/LambderApiIdempotency.js

@@ -1,4 +1,4 @@
-import { LambderApiError } from "../shared/LambderApiError.js";
+import { LambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderResponse, normalizeHeaders } from "../core/LambderResponse.js";
 /** A crashed original must not block retries forever: pending claims expire on their own. */
 const IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
@@ -40,7 +40,7 @@ export class LambderApiIdempotencyEngine {
             const content = `Invalid idempotency key: must be a string of ${IDEMPOTENCY_MIN_KEY_LENGTH}-${IDEMPOTENCY_MAX_KEY_LENGTH} characters.`;
             throw new LambderApiError(content, {
                 statusCode: 400,
-                errorMessage: { type: "error", content },
+                errorMessage: { type: "error", code: LAMBDER_REFUSAL_CODES.invalidIdempotencyKey, content },
             });
         }
         return rawKey;
@@ -116,7 +116,7 @@ export class LambderApiIdempotencyEngine {
         if (begun.state === "pending") {
             throw new LambderApiError(`Duplicate request for "${apiName}": the original is still processing.`, {
                 statusCode: 409,
-                errorMessage: { type: "warning", content: "This request is already being processed." },
+                errorMessage: { type: "warning", code: LAMBDER_REFUSAL_CODES.duplicateInFlight, content: "This request is already being processed." },
             });
         }
         if (begun.state === "done") {

package/dist/policies/LambderApiRateLimits.d.ts

@@ -42,13 +42,12 @@ export declare function lambderRateLimitKey(key: {
 /** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
 export type LambderRateLimitPer = "ip" | "session" | LambderRateLimitKeyFn<any>;
 /**
- * What one budget spans. Required on every policy, so a declaration always
- * says what its numbers mean:
+ * What one budget spans:
  *
- * - "perApi": every API referencing the policy gets its own counter, so the
- *   windows are a per-API ceiling (three APIs referencing a 60/min policy
- *   allow one subject 180/min in total). An API may tune the windows in its
- *   declaration: `rateLimit: { name: { perMin: 20 } }`.
+ * - "perApi" (default): every API referencing the policy gets its own
+ *   counter, so the windows are a per-API ceiling (three APIs referencing a
+ *   60/min policy allow one subject 180/min in total). An API may tune the
+ *   windows in its declaration: `rateLimit: { name: { perMin: 20 } }`.
  * - "perPolicy": every API referencing the policy shares ONE counter, so the
  *   windows are one combined budget (e.g. one per-email allowance across
  *   send, register, and reset). The policy IS the group: to give user APIs
@@ -58,9 +57,9 @@ export type LambderRateLimitBudget = "perApi" | "perPolicy";
 /** A named rate-limit policy: fixed windows, the key one counter tracks, and what one budget spans. */
 export type LambderApiRateLimitPolicyConfig = LambderRateLimitPolicy & {
     per: LambderRateLimitPer;
-    /** Whether the windows are a per-API ceiling or one budget shared by every referencing API. See LambderRateLimitBudget. */
-    budget: LambderRateLimitBudget;
-    /** Envelope errorMessage for refused requests. Default: a warning saying too many requests. */
+    /** Whether the windows are a per-API ceiling (default) or one budget shared by every referencing API. See LambderRateLimitBudget. */
+    budget?: LambderRateLimitBudget;
+    /** Envelope errorMessage for refused requests; inherits code "lambder/rate-limited" unless it sets its own. Default: a warning saying too many requests. */
     errorMessage?: LambderRefusalMessage;
 };
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>> = {
@@ -94,8 +93,8 @@ export type LambderRateLimitOverride = LambderRateLimitPolicy & {
     errorMessage?: LambderRefusalMessage;
 };
 type LambderRateLimitOverrideFor<TPolicy> = TPolicy extends {
-    budget: "perApi";
-} ? LambderRateLimitOverride : Pick<LambderRateLimitOverride, "errorMessage">;
+    budget: "perPolicy";
+} ? Pick<LambderRateLimitOverride, "errorMessage"> : LambderRateLimitOverride;
 /**
  * The per-API `rateLimit` option: one policy name, an ordered list of names,
  * or an object map that can carry each policy's override (`true` applies the

package/dist/policies/LambderApiRateLimits.js

@@ -1,9 +1,9 @@
 import { RATE_LIMIT_WINDOWS } from "../stores/LambderDdbRateLimiter.js";
-import { LambderApiError } from "../shared/LambderApiError.js";
+import { LambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { parsePreflightSlice } from "./LambderApiGuards.js";
 const RATE_LIMIT_WINDOW_KEYS = RATE_LIMIT_WINDOWS.map((window) => window.key);
 /** Refusal a rate-limited request answers unless the policy or the API's override names its own. */
-const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", content: "Too many requests. Please try again later." };
+const DEFAULT_RATE_LIMIT_REFUSAL = { type: "warning", code: LAMBDER_REFUSAL_CODES.rateLimited, content: "Too many requests. Please try again later." };
 export function lambderRateLimitKey(key) { return key; }
 /** Normalize the three rateLimit-option forms into ordered entries; an explicit `undefined` map value declares nothing. */
 const toRateLimitEntries = (value) => {
@@ -41,8 +41,8 @@ export class LambderApiRateLimitsEngine {
                 throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
             }
             const budget = policy.budget;
-            if (budget !== "perApi" && budget !== "perPolicy") {
-                throw new Error(`Lambder: rate-limit policy "${name}" needs budget: "perApi" (each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
+            if (budget !== undefined && budget !== "perApi" && budget !== "perPolicy") {
+                throw new Error(`Lambder: rate-limit policy "${name}" has budget "${String(budget)}"; use "perApi" (default: each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
             }
         }
         this.limiter = config.limiter;
@@ -91,8 +91,11 @@ export class LambderApiRateLimitsEngine {
             const exceeded = await this.limiter.isRateLimited(trackerKey, limits);
             if (exceeded) {
                 const retryAfterSeconds = Math.max(1, exceeded.resetAt - Math.floor(Date.now() / 1000));
+                // A policy's (or override's) own message inherits the framework
+                // code unless it sets a more specific one of its own.
+                const message = override?.errorMessage ?? policy.errorMessage;
                 throw new LambderApiError(`Rate limited: "${apiName}" exceeded policy "${name}" (${exceeded.window}: ${exceeded.limit}).`, {
-                    errorMessage: override?.errorMessage ?? policy.errorMessage ?? DEFAULT_RATE_LIMIT_REFUSAL,
+                    errorMessage: message ? { code: LAMBDER_REFUSAL_CODES.rateLimited, ...message } : DEFAULT_RATE_LIMIT_REFUSAL,
                     statusCode: 429,
                     headers: { "Retry-After": String(retryAfterSeconds) },
                 });

package/dist/session/LambderSessionManager.d.ts

@@ -53,6 +53,23 @@ export type LambderSessionDataRefreshConfig<SessionData = any> = {
      */
     refresh: (session: LambderSessionContext<SessionData>) => Promise<SessionData | null>;
 };
+/**
+ * Brotli compression of session.data at rest. The option is `true` by
+ * default, which equals `{ minBytes: 0 }`: every record compressed. A
+ * compressed record carries the data's JSON as Brotli bytes (`dataBr`)
+ * beside its byte length (`dataBytes`), the scheme LambderDdbCache and
+ * LambderDdbIdempotency use. Below minBytes, or with compression off, the
+ * record keeps a plain `data` attribute. Reads accept both shapes, so the
+ * setting can be switched on or off on a live table: records written under
+ * the other setting keep reading, and each is rewritten in the current
+ * shape on its next write.
+ */
+export type LambderSessionCompressionConfig = {
+    /** JSON byte length from which data is stored compressed. Default: 0 (always). */
+    minBytes?: number;
+    /** Brotli quality (0-11), like LambderDdbCache. Default: 5. */
+    quality?: number;
+};
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -81,7 +98,8 @@ export default class LambderSessionManager {
     private enableSlidingExpiration;
     private slidingWriteIntervalSeconds;
     private dataRefresh;
-    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, }: {
+    private compression;
+    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, compression, }: {
         tableName: string;
         tableRegion: string;
         partitionKey: string;
@@ -90,6 +108,7 @@ export default class LambderSessionManager {
         enableSlidingExpiration?: boolean;
         slidingWriteIntervalSeconds?: number;
         dataRefresh?: LambderSessionDataRefreshConfig;
+        compression?: boolean | LambderSessionCompressionConfig;
     });
     private sessionUserKeyHasher;
     /**
@@ -101,6 +120,12 @@ export default class LambderSessionManager {
     private hashToken;
     private constantTimeCompare;
     private ddbGetItem;
+    /**
+     * Persists a session record. With compression on, `data` is stored as
+     * Brotli bytes (`dataBr`) beside its JSON byte length (`dataBytes`)
+     * once the JSON reaches minBytes; otherwise it stays a plain attribute.
+     * See LambderSessionCompressionConfig.
+     */
     private ddbPutItem;
     private ddbDeleteItem;
     private ddbQueryAllByPartitionKey;

package/dist/session/LambderSessionManager.js

@@ -1,6 +1,7 @@
 import crypto from "crypto";
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand } from "@aws-sdk/lib-dynamodb";
+import { brotliCompressText, brotliRestoreText } from "../stores/LambderDdbCompression.js";
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -35,7 +36,8 @@ export default class LambderSessionManager {
     enableSlidingExpiration;
     slidingWriteIntervalSeconds;
     dataRefresh;
-    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, }) {
+    compression;
+    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, compression = true, }) {
         this.tableName = tableName;
         this.sessionSalt = sessionSalt;
         this.partitionKey = partitionKey;
@@ -43,6 +45,19 @@ export default class LambderSessionManager {
         this.enableSlidingExpiration = enableSlidingExpiration;
         this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds ?? null;
         this.dataRefresh = dataRefresh ?? null;
+        const compressionConfig = compression === true ? {} : compression;
+        this.compression = compressionConfig ? {
+            minBytes: compressionConfig.minBytes ?? 0,
+            quality: compressionConfig.quality ?? 5,
+        } : null;
+        if (this.compression) {
+            if (!Number.isSafeInteger(this.compression.minBytes) || this.compression.minBytes < 0) {
+                throw new Error("compression.minBytes must be a non-negative integer");
+            }
+            if (!Number.isInteger(this.compression.quality) || this.compression.quality < 0 || this.compression.quality > 11) {
+                throw new Error("compression.quality must be an integer from 0 to 11");
+            }
+        }
         const ddbClient = new DynamoDBClient({ region: tableRegion });
         this.ddbDocumentClient = DynamoDBDocumentClient.from(ddbClient);
     }
@@ -74,7 +89,22 @@ export default class LambderSessionManager {
         return null;
     }
     ;
-    async ddbPutItem(item) {
+    /**
+     * Persists a session record. With compression on, `data` is stored as
+     * Brotli bytes (`dataBr`) beside its JSON byte length (`dataBytes`)
+     * once the JSON reaches minBytes; otherwise it stays a plain attribute.
+     * See LambderSessionCompressionConfig.
+     */
+    async ddbPutItem(session) {
+        const { data, ...item } = session;
+        const raw = this.compression && Buffer.from(JSON.stringify(data), "utf8");
+        if (this.compression && raw && raw.byteLength >= this.compression.minBytes) {
+            item.dataBr = await brotliCompressText(raw, this.compression.quality);
+            item.dataBytes = raw.byteLength;
+        }
+        else {
+            item.data = data;
+        }
         return await this.ddbDocumentClient.send(new PutCommand({ TableName: this.tableName, Item: item, }));
     }
     ;
@@ -169,6 +199,14 @@ export default class LambderSessionManager {
         }
         if (!session)
             return null;
+        // A compressed record (see ddbPutItem) decodes back into `data`. One
+        // that fails to decode throws, which the controller treats like any
+        // malformed record: no session.
+        if (session.dataBr) {
+            session.data = JSON.parse(await brotliRestoreText(session.dataBr, session.dataBytes));
+            delete session.dataBr;
+            delete session.dataBytes;
+        }
         if (!session.csrfTokenHash)
             return null;
         if (!session.sessionKey)

package/dist/shared/LambderApiError.d.ts

@@ -57,17 +57,43 @@ export declare class LambderApiError extends Error {
 export declare const isLambderApiError: (err: unknown) => err is LambderApiError;
 /**
  * The standard shape refusals carry on the envelope's errorMessage field.
- * The caller's errorMessageHandler receives it as-is; apps with their own
- * errorMessage vocabulary can keep using LambderApiError directly instead.
+ * `code` is the refusal's machine-readable identity: clients branch and
+ * translate on it and never string-match `content`, which stays the
+ * human-readable fallback for codes a client does not know yet. Apps keep
+ * their own typed code vocabulary; the framework's own refusals carry a
+ * LambderRefusalCode. The caller's errorMessageHandler receives the object
+ * as-is; apps with their own errorMessage vocabulary can keep using
+ * LambderApiError directly instead.
  */
 export type LambderRefusalMessage = {
     type: "warning" | "error" | "info";
+    /** Machine-readable identity of the refusal (the app's own vocabulary, or a LambderRefusalCode). */
+    code?: string;
     title?: string;
     content: string;
 };
+/**
+ * Codes the framework stamps on the refusals it authors itself, under the
+ * reserved `lambder/` prefix so app codes never collide. Compare against
+ * these constants on the client (exported from `lambder/client` too) rather
+ * than retyping the strings.
+ */
+export declare const LAMBDER_REFUSAL_CODES: {
+    /** A rate-limit policy refused (429). A policy's own errorMessage inherits this unless it sets a code. */
+    readonly rateLimited: "lambder/rate-limited";
+    /** The original of an idempotent request is still processing (409). */
+    readonly duplicateInFlight: "lambder/duplicate-in-flight";
+    /** The idempotencyKey is malformed (400). */
+    readonly invalidIdempotencyKey: "lambder/invalid-idempotency-key";
+    /** No API is registered under the requested name. */
+    readonly apiNotFound: "lambder/api-not-found";
+};
+export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
 export type LambderRefuseOptions = {
     /** Rendering intent for the client's errorMessageHandler. Default: "warning". */
     type?: LambderRefusalMessage["type"];
+    /** Machine-readable identity of the refusal, for clients to branch and translate on. */
+    code?: string;
     /** Optional heading shown above the content. */
     title?: string;
     /** Sets the envelope's notAuthorized flag (routed to the caller's notAuthorizedHandler). */

package/dist/shared/LambderApiError.js

@@ -38,6 +38,22 @@ export class LambderApiError extends Error {
 }
 /** Brand-based type guard (see LambderApiError.isLambderApiError). */
 export const isLambderApiError = (err) => err instanceof Error && err.isLambderApiError === true;
+/**
+ * Codes the framework stamps on the refusals it authors itself, under the
+ * reserved `lambder/` prefix so app codes never collide. Compare against
+ * these constants on the client (exported from `lambder/client` too) rather
+ * than retyping the strings.
+ */
+export const LAMBDER_REFUSAL_CODES = {
+    /** A rate-limit policy refused (429). A policy's own errorMessage inherits this unless it sets a code. */
+    rateLimited: "lambder/rate-limited",
+    /** The original of an idempotent request is still processing (409). */
+    duplicateInFlight: "lambder/duplicate-in-flight",
+    /** The idempotencyKey is malformed (400). */
+    invalidIdempotencyKey: "lambder/invalid-idempotency-key",
+    /** No API is registered under the requested name. */
+    apiNotFound: "lambder/api-not-found",
+};
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid
  * input, not allowed) with a user-facing message. Throws a LambderApiError
@@ -54,6 +70,7 @@ export const refuse = (content, options = {}) => {
     throw new LambderApiError(content, {
         errorMessage: {
             type: options.type ?? "warning",
+            ...(options.code !== undefined ? { code: options.code } : {}),
             ...(options.title !== undefined ? { title: options.title } : {}),
             content,
         },

package/dist/stores/LambderDdbCache.js

@@ -1,6 +1,6 @@
 import { BatchWriteItemCommand, DeleteItemCommand, DynamoDBClient, GetItemCommand, PutItemCommand, QueryCommand, } from "@aws-sdk/client-dynamodb";
 import { getCrypto } from "../shared/node-polyfills.js";
-import { brotliCompressText, brotliDecompressText } from "./LambderDdbCompression.js";
+import { brotliCompressText, brotliRestoreText } from "./LambderDdbCompression.js";
 import { LRUCache } from "lru-cache";
 const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
 const DEFAULT_CHUNK_BYTES = 350 * 1024;
@@ -14,7 +14,8 @@ const MAX_BATCH_RETRIES = 8;
 // 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
-// are shared with LambderDdbIdempotency via ./LambderDdbCompression.js.
+// are shared with LambderDdbIdempotency and LambderSessionManager via
+// ./LambderDdbCompression.js.
 const requireCrypto = async () => {
     const crypto = await getCrypto();
     if (!crypto)
@@ -96,10 +97,7 @@ export class LambderDdbCache {
         const nowSeconds = this.nowSeconds();
         if (cached && cached.expiresAt > nowSeconds) {
             try {
-                const output = await brotliDecompressText(cached.compressed, this.maxValueBytes);
-                if (output.length === cached.uncompressedBytes) {
-                    return JSON.parse(output.toString("utf8"));
-                }
+                return JSON.parse(await brotliRestoreText(cached.compressed, cached.uncompressedBytes));
             }
             catch {
                 // Fall through to DynamoDB; the in-memory copy is disposable.
@@ -119,13 +117,9 @@ export class LambderDdbCache {
             if (await sha256(compressed) !== manifest.checksum) {
                 throw new Error("compressed checksum does not match manifest");
             }
-            const output = await brotliDecompressText(compressed, this.maxValueBytes);
-            if (output.length !== manifest.uncompressedBytes) {
-                throw new Error("uncompressed byte length does not match manifest");
-            }
-            const json = output.toString("utf8");
+            const json = await brotliRestoreText(compressed, manifest.uncompressedBytes);
             const parsed = JSON.parse(json);
-            this.remember(normalizedKey, compressed, output.length, manifest.expiresAt);
+            this.remember(normalizedKey, compressed, manifest.uncompressedBytes, manifest.expiresAt);
             return parsed;
         }
         catch (error) {

package/dist/stores/LambderDdbCompression.d.ts

@@ -1,3 +1,8 @@
 export declare const brotliCompressText: (input: Buffer, quality: number) => Promise<Buffer>;
-/** maxOutputLength bounds decompression so a corrupt record cannot balloon memory. */
-export declare const brotliDecompressText: (input: Buffer, maxOutputLength: number) => Promise<Buffer>;
+/**
+ * Restores text stored as Brotli bytes beside its declared UTF-8 byte length.
+ * The length bounds the decompression and the output must match it exactly,
+ * so a truncated or tampered record fails instead of decoding to something
+ * else.
+ */
+export declare const brotliRestoreText: (compressed: Uint8Array, declaredBytes: number) => Promise<string>;

package/dist/stores/LambderDdbCompression.js

@@ -1,8 +1,11 @@
 import { getZlib } from "../shared/node-polyfills.js";
 // Brotli compression shared by the DynamoDB-backed stores (LambderDdbCache,
-// LambderDdbIdempotency). Values they persist are text (JSON), so TEXT mode;
-// zlib is loaded lazily through node-polyfills so these modules can sit in a
-// frontend bundle's import graph (via the package root) without breaking.
+// LambderDdbIdempotency, LambderSessionManager). Values they persist are text
+// (JSON), so TEXT mode, and they all store it the same way: the Brotli bytes
+// beside the text's original UTF-8 byte length, which bounds the decompression
+// (a corrupt record cannot balloon memory) and verifies it. zlib is loaded
+// lazily through node-polyfills so these modules can sit in a frontend
+// bundle's import graph (via the package root) without breaking.
 const requireZlib = async () => {
     const zlib = await getZlib();
     if (!zlib)
@@ -25,15 +28,27 @@ export const brotliCompressText = async (input, quality) => {
         });
     });
 };
-/** maxOutputLength bounds decompression so a corrupt record cannot balloon memory. */
-export const brotliDecompressText = async (input, maxOutputLength) => {
+/**
+ * Restores text stored as Brotli bytes beside its declared UTF-8 byte length.
+ * The length bounds the decompression and the output must match it exactly,
+ * so a truncated or tampered record fails instead of decoding to something
+ * else.
+ */
+export const brotliRestoreText = async (compressed, declaredBytes) => {
+    if (!Number.isSafeInteger(declaredBytes) || declaredBytes <= 0) {
+        throw new Error("compressed record is missing its byte length");
+    }
     const zlib = await requireZlib();
-    return new Promise((resolve, reject) => {
-        zlib.brotliDecompress(input, { maxOutputLength }, (error, output) => {
+    const output = await new Promise((resolve, reject) => {
+        zlib.brotliDecompress(Buffer.from(compressed), { maxOutputLength: declaredBytes }, (error, result) => {
             if (error)
                 reject(error);
             else
-                resolve(output);
+                resolve(result);
         });
     });
+    if (output.length !== declaredBytes) {
+        throw new Error("decompressed length does not match the record");
+    }
+    return output.toString("utf8");
 };

package/dist/stores/LambderDdbIdempotency.js

@@ -1,6 +1,6 @@
 import crypto from "crypto";
 import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } from "@aws-sdk/client-dynamodb";
-import { brotliCompressText, brotliDecompressText } from "./LambderDdbCompression.js";
+import { brotliCompressText, brotliRestoreText } from "./LambderDdbCompression.js";
 /** Bodies at or above this size are stored Brotli-compressed; smaller ones stay plain. */
 const COMPRESS_MIN_BYTES = 1024;
 /**
@@ -67,16 +67,8 @@ export class LambderDdbIdempotency {
     /** A stored item's response body: plain (`body`) or Brotli (`bodyBr` + `bodyBytes`). */
     static async readItemBody(item) {
         const compressed = item.bodyBr?.B;
-        if (compressed) {
-            const declaredBytes = Number(item.bodyBytes?.N ?? 0);
-            if (!declaredBytes)
-                throw new Error("LambderDdbIdempotency: compressed record is missing bodyBytes.");
-            const output = await brotliDecompressText(Buffer.from(compressed), declaredBytes);
-            if (output.length !== declaredBytes) {
-                throw new Error("LambderDdbIdempotency: stored body length does not match its record.");
-            }
-            return output.toString("utf8");
-        }
+        if (compressed)
+            return await brotliRestoreText(compressed, Number(item.bodyBytes?.N ?? 0));
         return item.body?.S ?? "";
     }
     /**

package/package.json

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