lambder 5.1.3 → 6.0.1

package/dist/shared/LambderRequestPayload.d.ts

@@ -4,10 +4,11 @@
  * When a LambderCaller call's payload clears the configured size, the caller
  * sends the payload's JSON as `payloadGz` (gzip bytes, base64) beside
  * `payloadBytes` (its UTF-8 byte length) in place of `payload`, and the
- * server restores it before anything reads the payload. Everything else in
- * the envelope (apiName, version, token, siteHost, guardInputs,
- * idempotencyKey) stays plain text, so routing, logging and request mocking
- * are unaffected.
+ * server restores it before anything reads the payload. A Node caller
+ * (LambderInvokeCaller) sends `payloadBr` instead, Brotli under the same
+ * rules; the server accepts either. Everything else in the envelope
+ * (apiName, version, token, siteHost, guardInputs, idempotencyKey) stays
+ * plain text, so routing, logging and request mocking are unaffected.
  *
  * Base64 inside the JSON envelope, rather than a binary body with
  * Content-Encoding: API Gateway hands a binary request body to Lambda
@@ -26,12 +27,23 @@
  */
 import type { LambderCompressionOption } from "./LambderCompressionOption.js";
 /** Envelope field carrying the base64 gzip of the payload's JSON. */
-export declare const COMPRESSED_PAYLOAD_FIELD = "payloadGz";
+export declare const COMPRESSED_PAYLOAD_GZ_FIELD = "payloadGz";
+/**
+ * Envelope field carrying the base64 Brotli of the payload's JSON: the same
+ * pair as payloadGz for a caller that can produce Brotli (a Node caller,
+ * LambderInvokeCaller). A request carries one of the two, never both.
+ */
+export declare const COMPRESSED_PAYLOAD_BR_FIELD = "payloadBr";
 /** Envelope field carrying the UTF-8 byte length of that JSON before compression. */
 export declare const COMPRESSED_PAYLOAD_BYTES_FIELD = "payloadBytes";
-/** The pair a compressed call sends in place of `payload`. */
-export type LambderCompressedPayload = {
-    [COMPRESSED_PAYLOAD_FIELD]: string;
+/** The pair a gzip-compressing call sends in place of `payload`. */
+export type LambderCompressedGzipPayload = {
+    [COMPRESSED_PAYLOAD_GZ_FIELD]: string;
+    [COMPRESSED_PAYLOAD_BYTES_FIELD]: number;
+};
+/** The pair a Brotli-compressing call sends in place of `payload`. */
+export type LambderCompressedBrotliPayload = {
+    [COMPRESSED_PAYLOAD_BR_FIELD]: string;
     [COMPRESSED_PAYLOAD_BYTES_FIELD]: number;
 };
 /**
@@ -51,30 +63,41 @@ export type LambderRequestCompressionOption = LambderCompressionOption<LambderRe
  */
 export declare const DEFAULT_REQUEST_COMPRESSION_SETTINGS: LambderRequestCompressionSettings;
 /**
- * Default ceiling for a restored payload. Lambda's ~6MB invoke cap already
- * bounds the compressed bytes; this bounds what they may expand to, so a
- * highly compressible body cannot exhaust the function's memory.
+ * Default ceiling for a restored payload, a request's on the server
+ * (maxRequestPayloadBytes) or an answer's on the invoke caller
+ * (maxResponsePayloadBytes). Lambda's ~6MB invoke cap already bounds the
+ * compressed bytes; this bounds what they may expand to, so a highly
+ * compressible body cannot exhaust the function's memory.
  */
-export declare const DEFAULT_MAX_REQUEST_PAYLOAD_BYTES = 20000000;
+export declare const DEFAULT_MAX_RESTORED_PAYLOAD_BYTES = 20000000;
+/**
+ * The two rules every compressed payload follows, whichever algorithm made
+ * the bytes: nothing below the threshold is compressed, and the compressed
+ * form is only ever sent when its base64 is smaller than the JSON it
+ * replaces. The threshold is measured on real UTF-8 bytes, not string
+ * length, so a payload of multi-byte text is judged by what actually goes on
+ * the wire. `compress` is the algorithm: the browser's CompressionStream for
+ * gzip, zlib for Brotli (LambderInvokeCaller); both go through here so the
+ * rules cannot drift between them.
+ */
+export declare const compressPayloadWith: <TField extends string>(json: string, minBytes: number, field: TField, compress: (bytes: Uint8Array<ArrayBuffer>) => Promise<Uint8Array>) => Promise<({ [K in TField]: string; } & {
+    [COMPRESSED_PAYLOAD_BYTES_FIELD]: number;
+}) | null>;
 /** True when this runtime can compress request payloads (browsers, and Node 18+). */
 export declare const isRequestCompressionAvailable: () => boolean;
 /**
  * Gzip one payload's JSON for sending, or null when the plain JSON should go
- * instead: below the threshold, or when compressing did not make it smaller.
- * The threshold is measured on real UTF-8 bytes, not string length, so a
- * payload of multi-byte text is judged by what actually goes on the wire.
- *
- * The second null matters for the payloads most likely to be large: a
- * base64 image gzips to nearly its own size, and base64 then inflates the
- * result past the original. Sending that would cost CPU on both ends for a
- * request that got bigger, so the compressed form is only ever sent when it
- * is smaller than the JSON it replaces.
+ * instead (see compressPayloadWith for the two rules). The second null
+ * matters for the payloads most likely to be large: a base64 image gzips to
+ * nearly its own size, and base64 then inflates the result past the
+ * original. Sending that would cost CPU on both ends for a request that got
+ * bigger, so the compressed form is only ever sent when it is smaller.
  */
-export declare const compressPayloadJson: (json: string, minBytes: number) => Promise<LambderCompressedPayload | null>;
+export declare const compressPayloadGzip: (json: string, minBytes: number) => Promise<LambderCompressedGzipPayload | null>;
 /**
  * Restores a payload the caller compressed, for request mocking
  * (LambderMSW), so a mock handler receives the same payload the server
  * would. The server does NOT use this: it decompresses through zlib, whose
  * bounded output is what makes an untrusted body safe to expand.
  */
-export declare const decompressPayloadJson: (payloadGz: string) => Promise<unknown>;
+export declare const decompressPayloadGzip: (payloadGz: string) => Promise<unknown>;

package/dist/shared/LambderRequestPayload.js

@@ -4,10 +4,11 @@
  * When a LambderCaller call's payload clears the configured size, the caller
  * sends the payload's JSON as `payloadGz` (gzip bytes, base64) beside
  * `payloadBytes` (its UTF-8 byte length) in place of `payload`, and the
- * server restores it before anything reads the payload. Everything else in
- * the envelope (apiName, version, token, siteHost, guardInputs,
- * idempotencyKey) stays plain text, so routing, logging and request mocking
- * are unaffected.
+ * server restores it before anything reads the payload. A Node caller
+ * (LambderInvokeCaller) sends `payloadBr` instead, Brotli under the same
+ * rules; the server accepts either. Everything else in the envelope
+ * (apiName, version, token, siteHost, guardInputs, idempotencyKey) stays
+ * plain text, so routing, logging and request mocking are unaffected.
  *
  * Base64 inside the JSON envelope, rather than a binary body with
  * Content-Encoding: API Gateway hands a binary request body to Lambda
@@ -25,7 +26,13 @@
  * body fails instead of expanding without limit.
  */
 /** Envelope field carrying the base64 gzip of the payload's JSON. */
-export const COMPRESSED_PAYLOAD_FIELD = "payloadGz";
+export const COMPRESSED_PAYLOAD_GZ_FIELD = "payloadGz";
+/**
+ * Envelope field carrying the base64 Brotli of the payload's JSON: the same
+ * pair as payloadGz for a caller that can produce Brotli (a Node caller,
+ * LambderInvokeCaller). A request carries one of the two, never both.
+ */
+export const COMPRESSED_PAYLOAD_BR_FIELD = "payloadBr";
 /** Envelope field carrying the UTF-8 byte length of that JSON before compression. */
 export const COMPRESSED_PAYLOAD_BYTES_FIELD = "payloadBytes";
 /**
@@ -37,13 +44,17 @@ export const COMPRESSED_PAYLOAD_BYTES_FIELD = "payloadBytes";
  */
 export const DEFAULT_REQUEST_COMPRESSION_SETTINGS = { minBytes: 4096 };
 /**
- * Default ceiling for a restored payload. Lambda's ~6MB invoke cap already
- * bounds the compressed bytes; this bounds what they may expand to, so a
- * highly compressible body cannot exhaust the function's memory.
+ * Default ceiling for a restored payload, a request's on the server
+ * (maxRequestPayloadBytes) or an answer's on the invoke caller
+ * (maxResponsePayloadBytes). Lambda's ~6MB invoke cap already bounds the
+ * compressed bytes; this bounds what they may expand to, so a highly
+ * compressible body cannot exhaust the function's memory.
  */
-export const DEFAULT_MAX_REQUEST_PAYLOAD_BYTES = 20_000_000;
-/** Chunked so a large payload cannot overflow the argument list of String.fromCharCode. */
+export const DEFAULT_MAX_RESTORED_PAYLOAD_BYTES = 20_000_000;
+/** Buffer where there is one (Node); otherwise chunked so a large payload cannot overflow the argument list of String.fromCharCode. */
 const bytesToBase64 = (bytes) => {
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
     const chunkSize = 0x8000;
     let binary = "";
     for (let i = 0; i < bytes.length; i += chunkSize) {
@@ -51,41 +62,46 @@ const bytesToBase64 = (bytes) => {
     }
     return btoa(binary);
 };
-/** True when this runtime can compress request payloads (browsers, and Node 18+). */
-export const isRequestCompressionAvailable = () => typeof CompressionStream !== "undefined" && typeof btoa !== "undefined";
 /**
- * Gzip one payload's JSON for sending, or null when the plain JSON should go
- * instead: below the threshold, or when compressing did not make it smaller.
- * The threshold is measured on real UTF-8 bytes, not string length, so a
- * payload of multi-byte text is judged by what actually goes on the wire.
- *
- * The second null matters for the payloads most likely to be large: a
- * base64 image gzips to nearly its own size, and base64 then inflates the
- * result past the original. Sending that would cost CPU on both ends for a
- * request that got bigger, so the compressed form is only ever sent when it
- * is smaller than the JSON it replaces.
+ * The two rules every compressed payload follows, whichever algorithm made
+ * the bytes: nothing below the threshold is compressed, and the compressed
+ * form is only ever sent when its base64 is smaller than the JSON it
+ * replaces. The threshold is measured on real UTF-8 bytes, not string
+ * length, so a payload of multi-byte text is judged by what actually goes on
+ * the wire. `compress` is the algorithm: the browser's CompressionStream for
+ * gzip, zlib for Brotli (LambderInvokeCaller); both go through here so the
+ * rules cannot drift between them.
  */
-export const compressPayloadJson = async (json, minBytes) => {
+export const compressPayloadWith = async (json, minBytes, field, compress) => {
     const encoded = new TextEncoder().encode(json);
     if (encoded.length < minBytes)
         return null;
-    const stream = new Blob([encoded]).stream().pipeThrough(new CompressionStream("gzip"));
-    const compressed = new Uint8Array(await new Response(stream).arrayBuffer());
-    const base64 = bytesToBase64(compressed);
+    const base64 = bytesToBase64(await compress(encoded));
     if (base64.length >= encoded.length)
         return null;
-    return {
-        [COMPRESSED_PAYLOAD_FIELD]: base64,
-        [COMPRESSED_PAYLOAD_BYTES_FIELD]: encoded.length,
-    };
+    return { [field]: base64, [COMPRESSED_PAYLOAD_BYTES_FIELD]: encoded.length };
 };
+/** True when this runtime can compress request payloads (browsers, and Node 18+). */
+export const isRequestCompressionAvailable = () => typeof CompressionStream !== "undefined" && typeof btoa !== "undefined";
+/**
+ * Gzip one payload's JSON for sending, or null when the plain JSON should go
+ * instead (see compressPayloadWith for the two rules). The second null
+ * matters for the payloads most likely to be large: a base64 image gzips to
+ * nearly its own size, and base64 then inflates the result past the
+ * original. Sending that would cost CPU on both ends for a request that got
+ * bigger, so the compressed form is only ever sent when it is smaller.
+ */
+export const compressPayloadGzip = (json, minBytes) => compressPayloadWith(json, minBytes, COMPRESSED_PAYLOAD_GZ_FIELD, async (bytes) => {
+    const stream = new Blob([bytes]).stream().pipeThrough(new CompressionStream("gzip"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+});
 /**
  * Restores a payload the caller compressed, for request mocking
  * (LambderMSW), so a mock handler receives the same payload the server
  * would. The server does NOT use this: it decompresses through zlib, whose
  * bounded output is what makes an untrusted body safe to expand.
  */
-export const decompressPayloadJson = async (payloadGz) => {
+export const decompressPayloadGzip = async (payloadGz) => {
     const binary = atob(payloadGz);
     const bytes = new Uint8Array(binary.length);
     for (let i = 0; i < binary.length; i += 1) {

package/dist/stores/LambderDdbCache.d.ts

@@ -1,4 +1,4 @@
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
 export interface LambderDdbCacheOptions {
     tableName: string;
@@ -72,7 +72,10 @@ export declare class LambderDdbCache {
     readonly tableName: string;
     readonly keyPrefix: string;
     readonly namespace: string;
-    private readonly client;
+    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
+    private readonly providedClient;
+    private readonly region;
+    private readyPromise;
     private readonly defaultTtlSeconds;
     private readonly chunkBytes;
     private readonly compression;
@@ -80,6 +83,8 @@ export declare class LambderDdbCache {
     private readonly memory;
     private readonly inFlight;
     constructor(options: LambderDdbCacheOptions);
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    private ready;
     get<T>(key: LambderCacheKey): Promise<T | undefined>;
     private getByAddress;
     has(key: LambderCacheKey): Promise<boolean>;

package/dist/stores/LambderDdbCache.js

@@ -1,6 +1,6 @@
-import { BatchWriteItemCommand, DeleteItemCommand, DynamoDBClient, GetItemCommand, PutItemCommand, QueryCommand, } from "@aws-sdk/client-dynamodb";
+import { loadDynamoClientSdk } from "./LambderDdbSdk.js";
 import { getCrypto } from "../shared/node-polyfills.js";
-import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+import { compressText, restoreText } from "../shared/LambderCompressionCodec.js";
 import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
 import { LRUCache } from "lru-cache";
 const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
@@ -84,7 +84,10 @@ export class LambderDdbCache {
     tableName;
     keyPrefix;
     namespace;
-    client;
+    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
+    providedClient;
+    region;
+    readyPromise;
     defaultTtlSeconds;
     chunkBytes;
     compression;
@@ -114,7 +117,15 @@ export class LambderDdbCache {
                 maxSize: positiveInteger(memoryMaxBytes, "memoryMaxBytes"),
                 sizeCalculation: (entry) => entry.stored.length,
             });
-        this.client = options.client ?? new DynamoDBClient({ region: options.region ?? "us-east-1" });
+        this.providedClient = options.client;
+        this.region = options.region ?? "us-east-1";
+    }
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    ready() {
+        this.readyPromise ??= loadDynamoClientSdk("LambderDdbCache")
+            .then((sdk) => ({ sdk, client: this.providedClient ?? new sdk.DynamoDBClient({ region: this.region }) }))
+            .catch((error) => { this.readyPromise = undefined; throw error; });
+        return this.readyPromise;
     }
     async get(key) {
         return await this.getByAddress(this.normalizeKey(key));
@@ -205,7 +216,8 @@ export class LambderDdbCache {
             },
         }));
         await this.batchWrite(writes);
-        await this.client.send(new PutItemCommand({
+        const { client, sdk } = await this.ready();
+        await client.send(new sdk.PutItemCommand({
             TableName: this.tableName,
             Item: {
                 pk: { S: pk },
@@ -356,7 +368,8 @@ export class LambderDdbCache {
     async acquireLease(pk, address, owner, leaseSeconds) {
         const now = this.nowSeconds();
         try {
-            await this.client.send(new PutItemCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.PutItemCommand({
                 TableName: this.tableName,
                 Item: {
                     pk: { S: pk },
@@ -378,7 +391,8 @@ export class LambderDdbCache {
     }
     async releaseLease(pk, address, owner) {
         try {
-            await this.client.send(new DeleteItemCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.DeleteItemCommand({
                 TableName: this.tableName,
                 Key: { pk: { S: pk }, sk: { S: this.itemSortKey(address, LOCK_SORT_KEY) } },
                 ConditionExpression: "#owner = :owner",
@@ -393,7 +407,8 @@ export class LambderDdbCache {
         }
     }
     async readManifest(pk, address) {
-        const response = await this.client.send(new GetItemCommand({
+        const { client, sdk } = await this.ready();
+        const response = await client.send(new sdk.GetItemCommand({
             TableName: this.tableName,
             Key: { pk: { S: pk }, sk: { S: this.itemSortKey(address, META_SORT_KEY) } },
             ConsistentRead: false,
@@ -469,7 +484,8 @@ export class LambderDdbCache {
         const items = [];
         let cursor;
         do {
-            const response = await this.client.send(new QueryCommand({
+            const { client, sdk } = await this.ready();
+            const response = await client.send(new sdk.QueryCommand({
                 TableName: this.tableName,
                 KeyConditionExpression: options.prefix
                     ? "#pk = :pk AND begins_with(#sk, :prefix)"
@@ -494,7 +510,8 @@ export class LambderDdbCache {
     }
     async invalidateManifest(pk, address, version) {
         try {
-            await this.client.send(new DeleteItemCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.DeleteItemCommand({
                 TableName: this.tableName,
                 Key: { pk: { S: pk }, sk: { S: this.itemSortKey(address, META_SORT_KEY) } },
                 ConditionExpression: "#version = :version",
@@ -515,7 +532,8 @@ export class LambderDdbCache {
                 if (attempt >= MAX_BATCH_RETRIES) {
                     throw new Error(`DynamoDB cache batch write remained throttled after ${MAX_BATCH_RETRIES} attempts`);
                 }
-                const response = await this.client.send(new BatchWriteItemCommand({ RequestItems: { [this.tableName]: pending } }));
+                const { client, sdk } = await this.ready();
+                const response = await client.send(new sdk.BatchWriteItemCommand({ RequestItems: { [this.tableName]: pending } }));
                 pending = response.UnprocessedItems?.[this.tableName] ?? [];
                 if (pending.length > 0) {
                     const backoff = Math.min(25 * 2 ** attempt, 1_000) + Math.floor(Math.random() * 50);
@@ -526,7 +544,7 @@ export class LambderDdbCache {
     }
     /** The JSON text of a stored payload. */
     async decode(stored, encoding, uncompressedBytes) {
-        return encoding === "br" ? await restoreBoundedText(stored, uncompressedBytes, "br") : stored.toString("utf8");
+        return encoding === "br" ? await restoreText(stored, "br", { declaredBytes: uncompressedBytes }) : stored.toString("utf8");
     }
     remember(key, stored, encoding, uncompressedBytes, expiresAt) {
         if (!this.memory)

package/dist/stores/LambderDdbIdempotency.d.ts

@@ -1,4 +1,4 @@
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
 export interface LambderDdbIdempotencyOptions {
     tableName: string;
@@ -56,8 +56,13 @@ export declare class LambderDdbIdempotency {
     readonly tableName: string;
     readonly keyPrefix: string;
     private readonly compression;
-    private readonly client;
+    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
+    private readonly providedClient;
+    private readonly region;
+    private readyPromise;
     constructor(options: LambderDdbIdempotencyOptions);
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    private ready;
     private itemKey;
     /** Parse a stored item's response headers. */
     private static readItemHeaders;

package/dist/stores/LambderDdbIdempotency.js

@@ -1,6 +1,6 @@
 import crypto from "crypto";
-import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } from "@aws-sdk/client-dynamodb";
-import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+import { loadDynamoClientSdk } from "./LambderDdbSdk.js";
+import { compressText, restoreText } from "../shared/LambderCompressionCodec.js";
 import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
 /** Bodies of 1KB or more are stored Brotli-compressed by default; smaller ones stay plain. */
 const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
@@ -38,14 +38,25 @@ export class LambderDdbIdempotency {
     tableName;
     keyPrefix;
     compression;
-    client;
+    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
+    providedClient;
+    region;
+    readyPromise;
     constructor(options) {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
         this.tableName = options.tableName;
         this.keyPrefix = options.keyPrefix ?? "IDEM";
         this.compression = resolveCompressionOption(options.compression, COMPRESSION_DEFAULTS);
-        this.client = options.client ?? new DynamoDBClient(options.region ? { region: options.region } : {});
+        this.providedClient = options.client;
+        this.region = options.region;
+    }
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    ready() {
+        this.readyPromise ??= loadDynamoClientSdk("LambderDdbIdempotency")
+            .then((sdk) => ({ sdk, client: this.providedClient ?? new sdk.DynamoDBClient(this.region ? { region: this.region } : {}) }))
+            .catch((error) => { this.readyPromise = undefined; throw error; });
+        return this.readyPromise;
     }
     itemKey(scopeKey) {
         return { pk: { S: `${this.keyPrefix}#${scopeKey}` }, sk: { S: "idem" } };
@@ -67,7 +78,7 @@ export class LambderDdbIdempotency {
     static async readItemBody(item) {
         const compressed = item.bodyBr?.B;
         if (compressed)
-            return await restoreBoundedText(compressed, Number(item.bodyBytes?.N ?? 0), "br");
+            return await restoreText(compressed, "br", { declaredBytes: Number(item.bodyBytes?.N ?? 0) });
         return item.body?.S ?? "";
     }
     /**
@@ -77,7 +88,8 @@ export class LambderDdbIdempotency {
      * proceeds to begin(), whose read is authoritative.
      */
     async peek(scopeKey) {
-        const existing = await this.client.send(new GetItemCommand({
+        const { client, sdk } = await this.ready();
+        const existing = await client.send(new sdk.GetItemCommand({
             TableName: this.tableName,
             Key: this.itemKey(scopeKey),
         }));
@@ -103,7 +115,8 @@ export class LambderDdbIdempotency {
         const nowSeconds = Math.floor(Date.now() / 1000);
         const ownerToken = crypto.randomBytes(16).toString("hex");
         try {
-            await this.client.send(new PutItemCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.PutItemCommand({
                 TableName: this.tableName,
                 Item: {
                     ...this.itemKey(scopeKey),
@@ -120,7 +133,8 @@ export class LambderDdbIdempotency {
             if (error.name !== "ConditionalCheckFailedException")
                 throw error;
         }
-        const existing = await this.client.send(new GetItemCommand({
+        const { client, sdk } = await this.ready();
+        const existing = await client.send(new sdk.GetItemCommand({
             TableName: this.tableName,
             Key: this.itemKey(scopeKey),
             ConsistentRead: true,
@@ -168,7 +182,8 @@ export class LambderDdbIdempotency {
             bodyAttributes = { body: { S: body } };
         }
         try {
-            await this.client.send(new PutItemCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.PutItemCommand({
                 TableName: this.tableName,
                 Item: {
                     ...this.itemKey(scopeKey),
@@ -197,7 +212,8 @@ export class LambderDdbIdempotency {
      */
     async abandon(scopeKey, ownerToken) {
         try {
-            await this.client.send(new DeleteItemCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.DeleteItemCommand({
                 TableName: this.tableName,
                 Key: this.itemKey(scopeKey),
                 ConditionExpression: "ownerToken = :owner",

package/dist/stores/LambderDdbRateLimiter.d.ts

@@ -1,4 +1,4 @@
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 /**
  * The fixed windows a policy may cap, smallest first (the evaluation order),
  * with their length. The policy type derives from this table, so the two can
@@ -68,10 +68,15 @@ export interface LambderDdbRateLimiterOptions {
 export declare class LambderDdbRateLimiter {
     readonly tableName: string;
     readonly keyPrefix: string;
-    private readonly client;
+    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
+    private readonly providedClient;
+    private readonly region;
+    private readyPromise;
     private readonly ttlWindowMultiplier;
     private readonly failOpen;
     constructor(options: LambderDdbRateLimiterOptions);
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    private ready;
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
      * and report whether any of them is over its limit, with the window's

package/dist/stores/LambderDdbRateLimiter.js

@@ -1,4 +1,4 @@
-import { DynamoDBClient, UpdateItemCommand, } from "@aws-sdk/client-dynamodb";
+import { loadDynamoClientSdk } from "./LambderDdbSdk.js";
 /**
  * The fixed windows a policy may cap, smallest first (the evaluation order),
  * with their length. The policy type derives from this table, so the two can
@@ -32,7 +32,10 @@ export const RATE_LIMIT_WINDOWS = [
 export class LambderDdbRateLimiter {
     tableName;
     keyPrefix;
-    client;
+    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
+    providedClient;
+    region;
+    readyPromise;
     ttlWindowMultiplier;
     failOpen;
     constructor(options) {
@@ -45,7 +48,15 @@ export class LambderDdbRateLimiter {
             throw new Error("ttlWindowMultiplier must be a number greater than or equal to 1");
         }
         this.failOpen = options.failOpen ?? false;
-        this.client = options.client ?? new DynamoDBClient(options.region ? { region: options.region } : {});
+        this.providedClient = options.client;
+        this.region = options.region;
+    }
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    ready() {
+        this.readyPromise ??= loadDynamoClientSdk("LambderDdbRateLimiter")
+            .then((sdk) => ({ sdk, client: this.providedClient ?? new sdk.DynamoDBClient(this.region ? { region: this.region } : {}) }))
+            .catch((error) => { this.readyPromise = undefined; throw error; });
+        return this.readyPromise;
     }
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
@@ -84,7 +95,8 @@ export class LambderDdbRateLimiter {
             },
         };
         try {
-            await this.client.send(new UpdateItemCommand(input));
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.UpdateItemCommand(input));
             return false;
         }
         catch (error) {

package/dist/stores/LambderDdbSdk.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The DynamoDB SDK, loaded on first use.
+ *
+ * `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` are optional peer
+ * dependencies, and an app that keeps no sessions and uses none of the
+ * DynamoDB stores should neither install them nor pay for loading them: a
+ * module-level import costs every cold start something and, bundled, makes
+ * every Lambder app reference both packages. So the session manager and the
+ * three stores import their types only and take the classes from here the
+ * first time they touch the table, the way LambderS3FileSource and
+ * LambderInvokeCaller load theirs. One loader per package, memoized for the
+ * container's life; a missing package fails that first call with the
+ * install hint rather than failing the import of lambder itself.
+ */
+export type LambderDynamoClientSdk = typeof import("@aws-sdk/client-dynamodb");
+export type LambderDynamoDocumentSdk = typeof import("@aws-sdk/lib-dynamodb");
+/** `@aws-sdk/client-dynamodb`, for the item-level API the stores speak and the client the session manager wraps. */
+export declare const loadDynamoClientSdk: (user: string) => Promise<LambderDynamoClientSdk>;
+/** `@aws-sdk/lib-dynamodb`, the document client the session manager reads and writes through. */
+export declare const loadDynamoDocumentSdk: (user: string) => Promise<LambderDynamoDocumentSdk>;

package/dist/stores/LambderDdbSdk.js

@@ -0,0 +1,31 @@
+/**
+ * The DynamoDB SDK, loaded on first use.
+ *
+ * `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` are optional peer
+ * dependencies, and an app that keeps no sessions and uses none of the
+ * DynamoDB stores should neither install them nor pay for loading them: a
+ * module-level import costs every cold start something and, bundled, makes
+ * every Lambder app reference both packages. So the session manager and the
+ * three stores import their types only and take the classes from here the
+ * first time they touch the table, the way LambderS3FileSource and
+ * LambderInvokeCaller load theirs. One loader per package, memoized for the
+ * container's life; a missing package fails that first call with the
+ * install hint rather than failing the import of lambder itself.
+ */
+let clientSdk;
+let documentSdk;
+const withInstallHint = (loading, packageName, user, reset) => loading.catch((cause) => {
+    // Not memoized: the package may be installed later in the same process (tests), and the next caller names itself.
+    reset();
+    throw new Error(`${user} requires ${packageName}: npm install ${packageName}`, { cause });
+});
+/** `@aws-sdk/client-dynamodb`, for the item-level API the stores speak and the client the session manager wraps. */
+export const loadDynamoClientSdk = (user) => {
+    clientSdk ??= withInstallHint(import("@aws-sdk/client-dynamodb"), "@aws-sdk/client-dynamodb", user, () => { clientSdk = undefined; });
+    return clientSdk;
+};
+/** `@aws-sdk/lib-dynamodb`, the document client the session manager reads and writes through. */
+export const loadDynamoDocumentSdk = (user) => {
+    documentSdk ??= withInstallHint(import("@aws-sdk/lib-dynamodb"), "@aws-sdk/lib-dynamodb", user, () => { documentSdk = undefined; });
+    return documentSdk;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "5.1.3",
+  "version": "6.0.1",
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [
     "lambda",
@@ -87,6 +87,7 @@
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.574.0",
+    "@aws-sdk/client-lambda": "^3.574.0",
     "@aws-sdk/client-s3": "^3.574.0",
     "@aws-sdk/lib-dynamodb": "^3.574.0",
     "msw": "^2.0.0",
@@ -96,6 +97,9 @@
     "@aws-sdk/client-dynamodb": {
       "optional": true
     },
+    "@aws-sdk/client-lambda": {
+      "optional": true
+    },
     "@aws-sdk/client-s3": {
       "optional": true
     },
@@ -111,6 +115,7 @@
   },
   "devDependencies": {
     "@aws-sdk/client-dynamodb": "^3.913.0",
+    "@aws-sdk/client-lambda": "^3.1131.0",
     "@aws-sdk/client-s3": "^3.1127.0",
     "@aws-sdk/lib-dynamodb": "^3.913.0",
     "@types/aws-lambda": "^8.10.136",