lambder 4.2.3 → 4.3.2

package/Readme.md

@@ -2,6 +2,12 @@
 
 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.
+
+- **One compression option everywhere**: `LambderDdbCache`, `LambderDdbIdempotency` and sessions take the same `compression` option (`true` for that store's defaults, `false` for off, `{ minBytes, quality }` to override), resolved by one shared function, and each store records a value's encoding so the option can be switched on or off on a live table. Defaults keep the previous behavior: the cache compresses everything, the idempotency store from 1KB. `compressionQuality` on the cache and idempotency store is replaced by `compression: { quality }`, and HTTP `compression` accepts `true` as `{ minBytes: 860 }`.
+
 **New in 4.2:**
 
 - **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.
@@ -302,6 +308,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 +360,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; the option (`LambderCompressionOption`) is the same one `LambderDdbCache` and `LambderDdbIdempotency` take. 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)`:
@@ -644,13 +666,13 @@ Request flow per API: session (session APIs) → idempotency replay lookup → r
 
 Preflight input slices (guard `apiInput`/`guardInput` values, rate-limit `apiInput` keys) answer a rejection through the same path as the API's own schema: `setApiInputValidationErrorHandler` when set, otherwise the standard 422 body. One failure, one shape, whichever schema rejected it.
 
-**Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation with `LambderCaller.createIdempotencyKey()` and reuse it on retries. Keys must be 16-200 characters and UNGUESSABLE random (shorter keys refuse with 400): on session APIs the scope is session + API name + key, and on public APIs it is the key itself + API name, deliberately NOT the client IP, because the retry idempotency exists for (a timeout followed by a network switch) frequently arrives from a new IP. Concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL (response headers included, so headers set via `res.setHeader`/`res.addHeader` replay too), and a crashed original releases its claim so a retry actually retries. The replay rule for failures: RESPONSES are stored and replayed, refusals returned as envelopes (`res.api(null, { errorMessage })`) and thrown responses (`res.die.*`) included; EXCEPTIONS are not, so a thrown `LambderApiError`/`refuse()` releases the claim and a retry re-executes and decides afresh. Stored bodies of 1KB or more are Brotli-compressed (the same scheme as LambderDdbCache; `compressionQuality` on the store, default 5): JSON envelopes typically shrink 5-10x, which cuts DynamoDB write cost, and the ~350KB item budget applies to the COMPRESSED bytes, so even large responses usually stay replayable. Responses with status ≥ 500, bodies over the budget even compressed, and responses that set cookies are never stored (replaying one request's Set-Cookie, e.g. session tokens, into another would be wrong; such APIs still get in-flight 409 dedupe, just not replays). Claims are owner-checked, so an original that stalls past the pending window can no longer overwrite or delete the claim a retry has since taken. Requests without a key execute normally.
+**Idempotency semantics**: the client sends an `idempotencyKey` per call (see LambderCaller below); generate it once per logical operation with `LambderCaller.createIdempotencyKey()` and reuse it on retries. Keys must be 16-200 characters and UNGUESSABLE random (shorter keys refuse with 400): on session APIs the scope is session + API name + key, and on public APIs it is the key itself + API name, deliberately NOT the client IP, because the retry idempotency exists for (a timeout followed by a network switch) frequently arrives from a new IP. Concurrent duplicates of an in-flight request refuse with 409, repeats of a completed one replay the stored response verbatim until the TTL (response headers included, so headers set via `res.setHeader`/`res.addHeader` replay too), and a crashed original releases its claim so a retry actually retries. The replay rule for failures: RESPONSES are stored and replayed, refusals returned as envelopes (`res.api(null, { errorMessage })`) and thrown responses (`res.die.*`) included; EXCEPTIONS are not, so a thrown `LambderApiError`/`refuse()` releases the claim and a retry re-executes and decides afresh. Stored bodies of 1KB or more are Brotli-compressed by default (the same scheme and `compression` option as LambderDdbCache: `true`, `false`, or `{ minBytes, quality }`, default `{ minBytes: 1024, quality: 5 }`; records of either shape read back, so it can be switched on a live table): JSON envelopes typically shrink 5-10x, which cuts DynamoDB write cost, and the ~350KB item budget applies to the COMPRESSED bytes, so even large responses usually stay replayable. Responses with status ≥ 500, bodies over the budget even compressed, and responses that set cookies are never stored (replaying one request's Set-Cookie, e.g. session tokens, into another would be wrong; such APIs still get in-flight 409 dedupe, just not replays). Claims are owner-checked, so an original that stalls past the pending window can no longer overwrite or delete the claim a retry has since taken. Requests without a key execute normally.
 
 Also enforced at registration: **duplicate API names throw** (dispatch is first-match, so a second registration of the same name would be silently dead code).
 
 ### 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, 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, and fail-open semantics. Server-only. **Full guide with table setup: [docs/DDB_CACHE.md](./docs/DDB_CACHE.md).**
 
 ```typescript
 import { LambderDdbCache } from "lambder";

package/dist/core/Lambder.d.ts

@@ -6,6 +6,7 @@ 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 { LambderCompressionOption } from "../stores/LambderDdbCompression.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 +89,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?: LambderCompressionOption;
 };
 /**
  * Everything an instance is configured with, in ONE declaration: base
@@ -101,8 +110,8 @@ export type LambderCreateOptions<TSessionData = any> = {
     publicPath?: string;
     apiPath?: string;
     apiVersion?: string;
-    /** Automatic gzip for compressible responses. Default: { minBytes: 860 }. Set false to disable. */
-    compression?: false | {
+    /** Automatic gzip for compressible responses. `true` (the default) is `{ minBytes: 860 }`; `false` disables it. */
+    compression?: boolean | {
         minBytes?: number;
     };
     /** Automatic ETag + If-None-Match 304 on GET/HEAD 200 responses. Default: true. */

package/dist/core/Lambder.js

@@ -72,7 +72,8 @@ export default class Lambder {
         this.finalizeOptions = {
             compression: options.compression === false
                 ? false
-                : { minBytes: options.compression?.minBytes ?? DEFAULT_FINALIZE_OPTIONS.compression.minBytes },
+                : { minBytes: (typeof options.compression === "object" ? options.compression.minBytes : undefined)
+                        ?? DEFAULT_FINALIZE_OPTIONS.compression.minBytes },
             etag: options.etag ?? DEFAULT_FINALIZE_OPTIONS.etag,
             maxResponseBytes: options.maxResponseBytes ?? DEFAULT_FINALIZE_OPTIONS.maxResponseBytes,
         };
@@ -90,6 +91,7 @@ export default class Lambder {
                 enableSlidingExpiration: session.enableSlidingExpiration,
                 slidingWriteIntervalSeconds: session.slidingWriteIntervalSeconds,
                 dataRefresh: session.dataRefresh,
+                compression: session.compression,
             });
             this.sessionCookieOptions = session.cookie ?? {};
             if (session.tokenCookieKey)

package/dist/index.d.ts

@@ -19,6 +19,7 @@ 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 { LambderCompressionOption, LambderCompressionConfig } from "./stores/LambderDdbCompression.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/session/LambderSessionManager.d.ts

@@ -1,3 +1,4 @@
+import { type LambderCompressionOption } from "../stores/LambderDdbCompression.js";
 export type LambderSessionContext<SessionData = any> = {
     [x: string]: any;
     /**
@@ -81,7 +82,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 +92,7 @@ export default class LambderSessionManager {
         enableSlidingExpiration?: boolean;
         slidingWriteIntervalSeconds?: number;
         dataRefresh?: LambderSessionDataRefreshConfig;
+        compression?: LambderCompressionOption;
     });
     private sessionUserKeyHasher;
     /**
@@ -101,6 +104,11 @@ 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.
+     */
     private ddbPutItem;
     private ddbDeleteItem;
     private ddbQueryAllByPartitionKey;

package/dist/session/LambderSessionManager.js

@@ -1,6 +1,16 @@
 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, resolveCompressionOption, } from "../stores/LambderDdbCompression.js";
+/**
+ * Session compression defaults: every record compressed (see
+ * LambderCompressionOption for the option's shape and toggle semantics).
+ * 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.
+ */
+const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -35,7 +45,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, }) {
         this.tableName = tableName;
         this.sessionSalt = sessionSalt;
         this.partitionKey = partitionKey;
@@ -43,6 +54,7 @@ export default class LambderSessionManager {
         this.enableSlidingExpiration = enableSlidingExpiration;
         this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds ?? null;
         this.dataRefresh = dataRefresh ?? null;
+        this.compression = resolveCompressionOption(compression, SESSION_COMPRESSION_DEFAULTS);
         const ddbClient = new DynamoDBClient({ region: tableRegion });
         this.ddbDocumentClient = DynamoDBDocumentClient.from(ddbClient);
     }
@@ -74,7 +86,21 @@ 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.
+     */
+    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 +195,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/stores/LambderDdbCache.d.ts

@@ -1,4 +1,5 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { type LambderCompressionOption } from "./LambderDdbCompression.js";
 export interface LambderDdbCacheOptions {
     tableName: string;
     region?: string;
@@ -7,7 +8,13 @@ export interface LambderDdbCacheOptions {
     namespace?: string;
     defaultTtlSeconds?: number;
     chunkBytes?: number;
-    compressionQuality?: number;
+    /**
+     * Brotli compression of stored values. `true` (the default) is
+     * `{ minBytes: 0, quality: 5 }`: every value compressed; `false` stores
+     * values plain; an object overrides the defaults. The manifest records
+     * each value's encoding, so it can be switched on or off on a live table.
+     */
+    compression?: LambderCompressionOption;
     maxValueBytes?: number;
     memoryMaxBytes?: number;
     client?: DynamoDBClient;
@@ -22,8 +29,10 @@ export interface LambderDdbCacheGetOrSetOptions extends LambderDdbCacheSetOption
 /**
  * Persistent JSON cache backed by DynamoDB.
  *
- * Values are Brotli-compressed. Values within the safe DynamoDB item budget are
- * stored directly in the manifest for a single-request read; larger values are
+ * Values are Brotli-compressed by default (`compression` option; the manifest
+ * records each value's encoding, so the option can be switched on a live
+ * table). Values within the safe DynamoDB item budget are stored directly in
+ * the manifest for a single-request read; larger values are
  * split into versioned binary chunks. A manifest is written only after every
  * chunk succeeds, so readers see either the previous complete version or the
  * new complete version. DynamoDB TTL is cleanup only; every read also checks
@@ -41,7 +50,7 @@ export declare class LambderDdbCache {
     private readonly client;
     private readonly defaultTtlSeconds;
     private readonly chunkBytes;
-    private readonly compressionQuality;
+    private readonly compression;
     private readonly maxValueBytes;
     private readonly memory;
     private readonly inFlight;
@@ -64,6 +73,8 @@ export declare class LambderDdbCache {
     private readChunks;
     private invalidateManifest;
     private batchWrite;
+    /** The JSON text of a stored payload. */
+    private decode;
     private remember;
     private normalizeKey;
     private partitionKey;

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, resolveCompressionOption, } from "./LambderDdbCompression.js";
 import { LRUCache } from "lru-cache";
 const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
 const DEFAULT_CHUNK_BYTES = 350 * 1024;
@@ -11,10 +11,13 @@ const META_SORT_KEY = "meta";
 const LOCK_SORT_KEY = "lock";
 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 };
 // 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)
@@ -39,8 +42,10 @@ const sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, mil
 /**
  * Persistent JSON cache backed by DynamoDB.
  *
- * Values are Brotli-compressed. Values within the safe DynamoDB item budget are
- * stored directly in the manifest for a single-request read; larger values are
+ * Values are Brotli-compressed by default (`compression` option; the manifest
+ * records each value's encoding, so the option can be switched on a live
+ * table). Values within the safe DynamoDB item budget are stored directly in
+ * the manifest for a single-request read; larger values are
  * split into versioned binary chunks. A manifest is written only after every
  * chunk succeeds, so readers see either the previous complete version or the
  * new complete version. DynamoDB TTL is cleanup only; every read also checks
@@ -58,7 +63,7 @@ export class LambderDdbCache {
     client;
     defaultTtlSeconds;
     chunkBytes;
-    compressionQuality;
+    compression;
     maxValueBytes;
     memory;
     inFlight = new Map();
@@ -76,17 +81,14 @@ export class LambderDdbCache {
         if (this.chunkBytes > MAX_SAFE_CHUNK_BYTES) {
             throw new Error(`chunkBytes must not exceed ${MAX_SAFE_CHUNK_BYTES}`);
         }
-        this.compressionQuality = options.compressionQuality ?? 5;
-        if (!Number.isInteger(this.compressionQuality) || this.compressionQuality < 0 || this.compressionQuality > 11) {
-            throw new Error("compressionQuality must be an integer from 0 to 11");
-        }
+        this.compression = resolveCompressionOption(options.compression, COMPRESSION_DEFAULTS);
         this.maxValueBytes = positiveInteger(options.maxValueBytes ?? DEFAULT_MAX_VALUE_BYTES, "maxValueBytes");
         const memoryMaxBytes = options.memoryMaxBytes ?? DEFAULT_MEMORY_BYTES;
         this.memory = memoryMaxBytes === 0
             ? null
             : new LRUCache({
                 maxSize: positiveInteger(memoryMaxBytes, "memoryMaxBytes"),
-                sizeCalculation: (entry) => entry.compressed.length,
+                sizeCalculation: (entry) => entry.stored.length,
             });
         this.client = options.client ?? new DynamoDBClient({ region: options.region ?? "us-east-1" });
     }
@@ -96,10 +98,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 this.decode(cached.stored, cached.encoding, cached.uncompressedBytes));
             }
             catch {
                 // Fall through to DynamoDB; the in-memory copy is disposable.
@@ -112,20 +111,16 @@ export class LambderDdbCache {
         if (!manifest || manifest.expiresAt <= nowSeconds)
             return undefined;
         try {
-            const compressed = manifest.inlineData ?? await this.readChunks(pk, manifest);
-            if (compressed.length !== manifest.compressedBytes) {
-                throw new Error("compressed byte length does not match manifest");
+            const stored = manifest.inlineData ?? await this.readChunks(pk, manifest);
+            if (stored.length !== manifest.storedBytes) {
+                throw new Error("stored byte length does not match manifest");
             }
-            if (await sha256(compressed) !== manifest.checksum) {
-                throw new Error("compressed checksum does not match manifest");
+            if (await sha256(stored) !== manifest.checksum) {
+                throw new Error("stored 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 this.decode(stored, manifest.encoding, manifest.uncompressedBytes);
             const parsed = JSON.parse(json);
-            this.remember(normalizedKey, compressed, output.length, manifest.expiresAt);
+            this.remember(normalizedKey, stored, manifest.encoding, manifest.uncompressedBytes, manifest.expiresAt);
             return parsed;
         }
         catch (error) {
@@ -155,18 +150,20 @@ export class LambderDdbCache {
         if (input.length > this.maxValueBytes) {
             throw new Error(`Cache value exceeds maxValueBytes (${input.length} > ${this.maxValueBytes})`);
         }
-        const compressed = await brotliCompressText(input, this.compressionQuality);
-        if (compressed.length > this.maxValueBytes) {
-            throw new Error(`Compressed cache value exceeds maxValueBytes (${compressed.length} > ${this.maxValueBytes})`);
+        const brotli = this.compression && input.length >= this.compression.minBytes ? this.compression : null;
+        const encoding = brotli ? "br" : "identity";
+        const stored = brotli ? await brotliCompressText(input, brotli.quality) : input;
+        if (stored.length > this.maxValueBytes) {
+            throw new Error(`Stored cache value exceeds maxValueBytes (${stored.length} > ${this.maxValueBytes})`);
         }
         const pk = await this.partitionKey(normalizedKey);
         const version = `${Date.now().toString(36)}-${await randomUUID()}`;
         const expiresAt = this.nowSeconds() + ttlSeconds;
         const chunks = [];
-        const inline = compressed.length <= this.chunkBytes;
+        const inline = stored.length <= this.chunkBytes;
         if (!inline) {
-            for (let offset = 0; offset < compressed.length; offset += this.chunkBytes) {
-                chunks.push(compressed.subarray(offset, offset + this.chunkBytes));
+            for (let offset = 0; offset < stored.length; offset += this.chunkBytes) {
+                chunks.push(stored.subarray(offset, offset + this.chunkBytes));
             }
         }
         const writes = chunks.map((chunk, index) => ({
@@ -187,16 +184,16 @@ export class LambderDdbCache {
                 sk: { S: META_SORT_KEY },
                 version: { S: version },
                 chunkCount: { N: String(chunks.length) },
-                compressedBytes: { N: String(compressed.length) },
+                storedBytes: { N: String(stored.length) },
                 uncompressedBytes: { N: String(input.length) },
-                checksum: { S: await sha256(compressed) },
-                encoding: { S: "br" },
+                checksum: { S: await sha256(stored) },
+                encoding: { S: encoding },
                 createdAt: { N: String(this.nowSeconds()) },
                 expiresAt: { N: String(expiresAt) },
-                ...(inline ? { data: { B: compressed } } : {}),
+                ...(inline ? { data: { B: stored } } : {}),
             },
         }));
-        this.remember(normalizedKey, compressed, input.length, expiresAt);
+        this.remember(normalizedKey, stored, encoding, input.length, expiresAt);
     }
     async delete(key) {
         const normalizedKey = this.normalizeKey(key);
@@ -350,37 +347,39 @@ export class LambderDdbCache {
         const version = item.version?.S;
         const encoding = item.encoding?.S;
         const chunkCount = Number(item.chunkCount?.N);
-        const compressedBytes = Number(item.compressedBytes?.N);
+        const storedBytes = Number(item.storedBytes?.N);
         const uncompressedBytes = Number(item.uncompressedBytes?.N);
         const expiresAt = Number(item.expiresAt?.N);
         const checksum = item.checksum?.S;
         const inlineData = item.data?.B == null ? undefined : Buffer.from(item.data.B);
         const validInline = inlineData !== undefined &&
             chunkCount === 0 &&
-            inlineData.length === compressedBytes &&
-            compressedBytes <= this.chunkBytes;
+            inlineData.length === storedBytes &&
+            storedBytes <= this.chunkBytes;
         const validChunks = inlineData === undefined &&
             chunkCount > 0 &&
-            chunkCount === Math.ceil(compressedBytes / this.chunkBytes);
+            chunkCount === Math.ceil(storedBytes / this.chunkBytes);
         if (!version ||
-            encoding !== "br" ||
+            (encoding !== "br" && encoding !== "identity") ||
             !checksum ||
             !Number.isSafeInteger(chunkCount) ||
             chunkCount < 0 ||
-            !Number.isSafeInteger(compressedBytes) ||
-            compressedBytes < 0 ||
-            compressedBytes > this.maxValueBytes ||
+            !Number.isSafeInteger(storedBytes) ||
+            storedBytes < 0 ||
+            storedBytes > this.maxValueBytes ||
             !Number.isSafeInteger(uncompressedBytes) ||
             uncompressedBytes < 0 ||
             uncompressedBytes > this.maxValueBytes ||
+            (encoding === "identity" && storedBytes !== uncompressedBytes) ||
             !Number.isSafeInteger(expiresAt) ||
             (!validInline && !validChunks)) {
             return undefined;
         }
         return {
             version,
+            encoding,
             chunkCount,
-            compressedBytes,
+            storedBytes,
             uncompressedBytes,
             checksum,
             expiresAt,
@@ -417,7 +416,7 @@ export class LambderDdbCache {
                 throw new Error(`DynamoDB cache entry has an invalid chunk index at ${index}`);
             }
         }
-        return Buffer.concat(chunks.map((chunk) => chunk.data), manifest.compressedBytes);
+        return Buffer.concat(chunks.map((chunk) => chunk.data), manifest.storedBytes);
     }
     async invalidateManifest(pk, version) {
         try {
@@ -451,13 +450,17 @@ export class LambderDdbCache {
             }
         }
     }
-    remember(key, compressed, uncompressedBytes, expiresAt) {
+    /** The JSON text of a stored payload. */
+    async decode(stored, encoding, uncompressedBytes) {
+        return encoding === "br" ? await brotliRestoreText(stored, uncompressedBytes) : stored.toString("utf8");
+    }
+    remember(key, stored, encoding, uncompressedBytes, expiresAt) {
         if (!this.memory)
             return;
         const ttl = expiresAt * 1000 - Date.now();
         if (ttl <= 0)
             return;
-        this.memory.set(key, { compressed, uncompressedBytes, expiresAt }, { ttl });
+        this.memory.set(key, { stored, encoding, uncompressedBytes, expiresAt }, { ttl });
     }
     normalizeKey(key) {
         if (typeof key !== "string" || !key.trim())

package/dist/stores/LambderDdbCompression.d.ts

@@ -1,3 +1,25 @@
+/**
+ * The compression option every store shares. `true` is on with the store's
+ * defaults, `false` is off, an object overrides the defaults: `minBytes` is
+ * the UTF-8 size from which a value is stored compressed (0: always),
+ * `quality` is Brotli 0-11. Values below minBytes are stored plain, and a
+ * store reads records of either shape, so the option 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 LambderCompressionConfig = {
+    minBytes?: number;
+    quality?: number;
+};
+export type LambderCompressionOption = boolean | LambderCompressionConfig;
+export type LambderCompressionSettings = Required<LambderCompressionConfig>;
+/** Resolves a store's compression option against its defaults: null when off. */
+export declare const resolveCompressionOption: (option: LambderCompressionOption | undefined, defaults: LambderCompressionSettings) => LambderCompressionSettings | null;
 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,18 @@
 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.
+/** Resolves a store's compression option against its defaults: null when off. */
+export const resolveCompressionOption = (option, defaults) => {
+    if (option === false)
+        return null;
+    const config = option === true || option === undefined ? {} : option;
+    const settings = { minBytes: config.minBytes ?? defaults.minBytes, quality: config.quality ?? defaults.quality };
+    if (!Number.isSafeInteger(settings.minBytes) || settings.minBytes < 0) {
+        throw new Error("compression.minBytes must be a non-negative integer");
+    }
+    if (!Number.isInteger(settings.quality) || settings.quality < 0 || settings.quality > 11) {
+        throw new Error("compression.quality must be an integer from 0 to 11");
+    }
+    return settings;
+};
 const requireZlib = async () => {
     const zlib = await getZlib();
     if (!zlib)
@@ -25,15 +35,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.d.ts

@@ -1,11 +1,17 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { type LambderCompressionOption } from "./LambderDdbCompression.js";
 export interface LambderDdbIdempotencyOptions {
     tableName: string;
     region?: string;
     /** Partition key prefix, keeps records separated from other systems in a shared table. Default: "IDEM". */
     keyPrefix?: string;
-    /** Brotli quality (0-11) for stored bodies, like LambderDdbCache. Default: 5. */
-    compressionQuality?: number;
+    /**
+     * Brotli compression of stored bodies. `true` (the default) is
+     * `{ minBytes: 1024, quality: 5 }`; `false` stores every body plain; an
+     * object overrides the defaults. Records of either shape read back, so
+     * it can be switched on or off on a live table.
+     */
+    compression?: LambderCompressionOption;
     client?: DynamoDBClient;
 }
 export type LambderIdempotencyDoneRecord = {
@@ -35,10 +41,11 @@ export type LambderIdempotencyBeginResult = {
  * and loses the scope to a retry can no longer overwrite or delete the
  * retry's claim (both settle calls become silent no-ops instead).
  *
- * Stored bodies of 1KB or more are Brotli-compressed (same scheme as
- * LambderDdbCache): the bodies are JSON envelopes that typically shrink
- * 5-10x, which cuts DynamoDB write units and lets large responses fit the
- * item budget instead of skipping replay storage.
+ * Stored bodies are Brotli-compressed from 1KB by default (same scheme as
+ * LambderDdbCache, see the `compression` option): the bodies are JSON
+ * envelopes that typically shrink 5-10x, which cuts DynamoDB write units
+ * and lets large responses fit the item budget instead of skipping replay
+ * storage.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on
  * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
@@ -48,7 +55,7 @@ export type LambderIdempotencyBeginResult = {
 export declare class LambderDdbIdempotency {
     readonly tableName: string;
     readonly keyPrefix: string;
-    private readonly compressionQuality;
+    private readonly compression;
     private readonly client;
     constructor(options: LambderDdbIdempotencyOptions);
     private itemKey;
@@ -74,10 +81,11 @@ export declare class LambderDdbIdempotency {
     }): Promise<LambderIdempotencyBeginResult>;
     /**
      * Store the response for replays, overwriting the pending claim. Bodies
-     * of COMPRESS_MIN_BYTES or more are stored Brotli-compressed (they are
-     * JSON envelopes, which typically shrink 5-10x), cutting DynamoDB write
-     * units and letting large responses fit the item budget; smaller bodies
-     * stay plain. Returns:
+     * from the compression option's minBytes are stored Brotli-compressed
+     * (they are JSON envelopes, which typically shrink 5-10x), cutting
+     * DynamoDB write units and letting large responses fit the item budget;
+     * smaller bodies, or all of them with compression off, stay plain.
+     * Returns:
      *
      * - "stored": the record is in place and will replay.
      * - "too-large": even compressed, the body exceeds the item budget;

package/dist/stores/LambderDdbIdempotency.js

@@ -1,8 +1,8 @@
 import crypto from "crypto";
 import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } from "@aws-sdk/client-dynamodb";
-import { brotliCompressText, brotliDecompressText } from "./LambderDdbCompression.js";
-/** Bodies at or above this size are stored Brotli-compressed; smaller ones stay plain. */
-const COMPRESS_MIN_BYTES = 1024;
+import { brotliCompressText, brotliRestoreText, resolveCompressionOption, } from "./LambderDdbCompression.js";
+/** Bodies of 1KB or more are stored Brotli-compressed by default; smaller ones stay plain. */
+const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
 /**
  * Stored-body budget inside DynamoDB's 400KB item limit (headers, keys and
  * attributes need headroom). Applies to the bytes actually stored, so a
@@ -22,10 +22,11 @@ const MAX_STORED_BODY_BYTES = 350_000;
  * and loses the scope to a retry can no longer overwrite or delete the
  * retry's claim (both settle calls become silent no-ops instead).
  *
- * Stored bodies of 1KB or more are Brotli-compressed (same scheme as
- * LambderDdbCache): the bodies are JSON envelopes that typically shrink
- * 5-10x, which cuts DynamoDB write units and lets large responses fit the
- * item budget instead of skipping replay storage.
+ * Stored bodies are Brotli-compressed from 1KB by default (same scheme as
+ * LambderDdbCache, see the `compression` option): the bodies are JSON
+ * envelopes that typically shrink 5-10x, which cuts DynamoDB write units
+ * and lets large responses fit the item budget instead of skipping replay
+ * storage.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on
  * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
@@ -35,17 +36,14 @@ const MAX_STORED_BODY_BYTES = 350_000;
 export class LambderDdbIdempotency {
     tableName;
     keyPrefix;
-    compressionQuality;
+    compression;
     client;
     constructor(options) {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
         this.tableName = options.tableName;
         this.keyPrefix = options.keyPrefix ?? "IDEM";
-        this.compressionQuality = options.compressionQuality ?? 5;
-        if (!Number.isInteger(this.compressionQuality) || this.compressionQuality < 0 || this.compressionQuality > 11) {
-            throw new Error("compressionQuality must be an integer from 0 to 11");
-        }
+        this.compression = resolveCompressionOption(options.compression, COMPRESSION_DEFAULTS);
         this.client = options.client ?? new DynamoDBClient(options.region ? { region: options.region } : {});
     }
     itemKey(scopeKey) {
@@ -67,16 +65,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 ?? "";
     }
     /**
@@ -150,10 +140,11 @@ export class LambderDdbIdempotency {
     }
     /**
      * Store the response for replays, overwriting the pending claim. Bodies
-     * of COMPRESS_MIN_BYTES or more are stored Brotli-compressed (they are
-     * JSON envelopes, which typically shrink 5-10x), cutting DynamoDB write
-     * units and letting large responses fit the item budget; smaller bodies
-     * stay plain. Returns:
+     * from the compression option's minBytes are stored Brotli-compressed
+     * (they are JSON envelopes, which typically shrink 5-10x), cutting
+     * DynamoDB write units and letting large responses fit the item budget;
+     * smaller bodies, or all of them with compression off, stay plain.
+     * Returns:
      *
      * - "stored": the record is in place and will replay.
      * - "too-large": even compressed, the body exceeds the item budget;
@@ -165,8 +156,8 @@ export class LambderDdbIdempotency {
         const nowSeconds = Math.floor(Date.now() / 1000);
         const rawBody = Buffer.from(body, "utf8");
         let bodyAttributes;
-        if (rawBody.byteLength >= COMPRESS_MIN_BYTES) {
-            const compressed = await brotliCompressText(rawBody, this.compressionQuality);
+        if (this.compression && rawBody.byteLength >= this.compression.minBytes) {
+            const compressed = await brotliCompressText(rawBody, this.compression.quality);
             if (compressed.byteLength > MAX_STORED_BODY_BYTES)
                 return "too-large";
             // bodyBytes bounds and verifies decompression on read.

package/package.json

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