lambder 4.3.1 → 4.4.1

package/Readme.md

@@ -2,10 +2,18 @@
 
 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.4:**
+
+- **`guardInputsProvider`** on `LambderCaller`: supply guardInput-mode guard values for every call from one place (the organization the UI is on, a device token) instead of at each call site; per-call `guardInputs` merge on top. Name the covered guards in the caller's second type parameter, `new LambderCaller<Contract, "orgPermission">({ guardInputsProvider, ... })`: calls to APIs whose guardInput guards are all covered no longer require the options argument, uncovered ones (a Turnstile token) still do, and naming guards makes the provider itself mandatory.
+- **Public file sources**: `servePublicFiles({ source })` serves from any `LambderPublicFileSource`: `LambderLocalFileSource` (a folder; the default, over `publicPath`), `LambderS3FileSource` (S3, or Cloudflare R2 and other S3-compatible stores via `clientConfig.endpoint`; `@aws-sdk/client-s3` is an optional peer dependency loaded on first read), or your own `{ read(relativePath) }`. The handler's traversal check, memory cache, mime fallback from the extension, Cache-Control, ETag and compression apply to every source. The `cacheControl` callback receives the relative file path.
+- **`expireSessionDataAllByKey(sessionKey)`** on the session manager and controller: marks the data of every session of a subject stale, so each renews via `dataRefresh` on its next read. The way to apply a role or permission change to a user immediately, without logging them out (`deleteSessionAllByKey`) and without waiting for the data TTL.
+
 **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.
@@ -158,8 +166,9 @@ lambder
     .addRoute({ path: "/stripe-webhook", method: "POST" }, (ctx, res) => {
         return res.json({ received: true });
     })
-    // Serve real files from publicPath. This is a terminal fallback slot, NOT
-    // a catch-all route, so it can never shadow routes registered after it.
+    // Serve real files (from publicPath by default; see "Public file sources"
+    // below for S3/R2). This is a terminal fallback slot, NOT a catch-all
+    // route, so it can never shadow routes registered after it.
     .servePublicFiles()
     // Serve the app shell for GET/HEAD page requests nothing else handled
     // (see "Hosting a frontend build" below).
@@ -357,6 +366,7 @@ Semantics:
 - The renewal write and the sliding-expiration write share a single DynamoDB put when both are due.
 - 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.
+- `expireSessionDataAllByKey(sessionKey)` stamps every session of a subject stale at once: call it after changing that subject's roles or permissions, and the change applies on their next request instead of within `ttlSeconds`, with no logout. It updates only `dataExpiresAt`, conditionally on the record still existing, so it neither resurrects a deleted session nor clobbers a concurrent write.
 
 #### Session data at rest (`compression`)
 
@@ -371,7 +381,7 @@ session: {
 }
 ```
 
-`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.
+`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
 
@@ -387,6 +397,7 @@ Access the session controller with `lambder.getSessionController(ctx)`:
 | `endSession()` | End session, delete from DDB |
 | `endSessionAll()` | End all sessions for this sessionKey (all devices) |
 | `deleteSessionAllByKey(sessionKey)` | Delete all sessions of any sessionKey (e.g. "log user X out everywhere") |
+| `expireSessionDataAllByKey(sessionKey)` | Mark the data of all sessions of a sessionKey stale, so each renews via `dataRefresh` on its next read (no logout) |
 | `regenerateSession()` | Regenerate token (use after password change) |
 
 ### Type-Safe Templating (html / xml)
@@ -430,6 +441,33 @@ const output = template.render({
 
 Lambder has no SPA-specific machinery; hosting a frontend build is a recipe built from three generic primitives: `servePublicFiles()` (terminal slot serving real files: memory-cached, immutable Cache-Control for hashed assets, ETag/gzip, falls through when missing), `serveIndexHtml()` (next fallback slot, GET/HEAD + non-file-path gated) and `res.templateFile()` (render an HTML file through the templating engine, compiled once and cached). **Full guide with the multi-tenant recipe: [docs/TEMPLATING.md](./docs/TEMPLATING.md).**
 
+#### Public file sources
+
+`servePublicFiles` reads through a `LambderPublicFileSource`, an object with one method, `read(relativePath)`, returning `{ body, mimeType? }` or `null` (the request then falls through). The handler does everything else for every source: traversal check, memory cache for warm invocations, mime fallback from the extension, Cache-Control (immutable for content-hashed names), ETag and compression. Built in:
+
+```typescript
+// Default: the publicPath folder bundled with the deployment.
+lambder.servePublicFiles();
+
+// S3. @aws-sdk/client-s3 is an optional peer dependency, loaded on first read.
+lambder.servePublicFiles({
+    source: new LambderS3FileSource({ bucket: "myapp-web", prefix: "v42/", clientConfig: { region: "eu-central-1" } }),
+});
+
+// Cloudflare R2, or any S3-compatible store: point the client at its endpoint.
+lambder.servePublicFiles({
+    source: new LambderS3FileSource({
+        bucket: "myapp-web",
+        clientConfig: { region: "auto", endpoint: "https://<account>.r2.cloudflarestorage.com", credentials: { accessKeyId, secretAccessKey } },
+    }),
+});
+
+// Anything else: implement read().
+lambder.servePublicFiles({ source: { read: async (relativePath) => myStore.get(relativePath) } });
+```
+
+A missing S3 object reads as null; grant `s3:ListBucket` besides `s3:GetObject`, otherwise S3 answers a missing key with AccessDenied, which propagates as an error instead of falling through. The object's Content-Type is used unless it is a generic octet-stream, in which case the extension decides. Lambda's ~6MB response cap still applies to anything proxied this way: redirect large downloads to the bucket or CDN URL instead of serving them.
+
 ```typescript
 // Zero-config single-tenant hosting:
 lambder.servePublicFiles().serveIndexHtml();
@@ -664,13 +702,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";
@@ -770,7 +808,7 @@ Also available:
 
 - **Timeouts**: pass `timeoutMs` in the constructor for a default (API Gateway caps around 29s, so ~30000 is sensible) and/or per call; timed-out calls abort the fetch and report `reason: 'timeout'`. A per-call `signal` combines with the timeout.
 - **Per-call handler overrides**: every constructor handler (`errorHandler`, `sessionExpiredHandler`, `errorMessageHandler`, ...) can be overridden in the options of a single `api`/`apiOutcome` call.
-- **Guard inputs**: for APIs whose guards run in guardInput mode, pass their values per call as `guardInputs: { <guardName>: value }`; the typed contract makes the options argument (and the correct value shape) mandatory for those APIs.
+- **Guard inputs**: for APIs whose guards run in guardInput mode, pass their values per call as `guardInputs: { <guardName>: value }`; the typed contract makes the options argument (and the correct value shape) mandatory for those APIs. A `guardInputsProvider` on the caller supplies values for every call from one place, keyed by guard name, with per-call `guardInputs` merged on top; name the guards it covers in the caller's second type parameter, `new LambderCaller<Contract, "orgPermission">({ guardInputsProvider: () => ({ orgPermission: { orgSlug } }), ... })`, and calls to APIs whose guardInput guards are all covered take an optional options argument again.
 - **Idempotency keys**: pass `idempotencyKey` per call for APIs declared idempotent on the server (see Declarative API Policies). Generate it once per logical operation with `LambderCaller.createIdempotencyKey()` (safe in insecure contexts where `crypto.randomUUID` is missing) and send the same key on retries; rotate after a confirmed success. `LambderCaller.createIdempotencyKeyScope()` packages that pattern for a component performing one operation repeatedly: read `scope.current` on every attempt, call `scope.rotate()` after a confirmed success. Keys must be unguessable random and 16-200 characters (they scope the replay record for logged-out clients); the server refuses shorter keys with a 400.
 
 ### Benefits

package/dist/client/LambderCaller.d.ts

@@ -5,14 +5,52 @@ type IsAny<T> = 0 extends (1 & T) ? true : false;
 type GuardInputsOf<TEntry> = TEntry extends {
     guardInputs: infer G;
 } ? G : never;
+/** Input type of guard G on one contract entry; never when that API does not declare it. */
+type GuardInputOf<TEntry, G extends string> = GuardInputsOf<TEntry> extends infer I ? (G extends keyof I ? I[G] : never) : never;
+/**
+ * What guardInputsProvider returns: for every provided guard name, the value
+ * the contract's APIs expect for it (a union across APIs when they differ).
+ * Naming a guard no API declares in guardInput mode resolves to never, so a
+ * typo fails the provider's return type instead of going missing at runtime.
+ */
+export type LambderProvidedGuardInputs<TContract, TProvided extends string> = IsAny<TContract> extends true ? Record<TProvided, unknown> : {
+    [G in TProvided]: {
+        [K in keyof TContract]: GuardInputOf<TContract[K], G>;
+    }[keyof TContract];
+};
+/**
+ * Supplies guardInputs for every call from one place (the organization the
+ * UI is on, a device token), keyed by guard name; per-call guardInputs
+ * merge on top. Name the guards it covers in the caller's second type
+ * parameter, `new LambderCaller<Contract, "orgPermission">`, and calls to
+ * APIs whose guardInput guards are all covered no longer require the
+ * options argument. May be async; a throw fails the call as an unknown
+ * error before anything is sent.
+ */
+export type LambderGuardInputsProvider<TContract, TProvided extends string> = (apiName: keyof TContract & string) => LambderProvidedGuardInputs<TContract, TProvided> | Promise<LambderProvidedGuardInputs<TContract, TProvided>>;
+/** Optional until the caller names provided guards: naming them without a provider would send nothing. */
+type GuardInputsProviderOption<TContract, TProvided extends string> = [
+    TProvided
+] extends [never] ? {
+    guardInputsProvider?: LambderGuardInputsProvider<TContract, TProvided>;
+} : {
+    guardInputsProvider: LambderGuardInputsProvider<TContract, TProvided>;
+};
+/** An API's guardInput guards the provider does not cover: those the call must still pass. */
+type RemainingGuardInputs<TEntry, TProvided extends string> = Omit<GuardInputsOf<TEntry>, TProvided>;
 /**
  * The options argument: optional normally, REQUIRED (with guardInputs) when
- * the API's contract declares guardInput-mode guards, so forgetting to send
- * a guard's value is a compile error at the call site.
+ * the API's contract declares guardInput-mode guards the provider does not
+ * cover, so forgetting to send a guard's value is a compile error at the
+ * call site. Provided guards may still be overridden per call.
  */
-type CallOptionsArg<TContract, TApiName> = IsAny<TContract> extends true ? [options?: LambderCallOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: LambderCallOptions] : [options: LambderCallOptions & {
-    guardInputs: GuardInputsOf<TContract[TApiName]>;
-}] : [options?: LambderCallOptions];
+type CallOptionsArg<TContract, TApiName, TProvided extends string> = IsAny<TContract> extends true ? [options?: LambderCallOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: LambderCallOptions] : [keyof RemainingGuardInputs<TContract[TApiName], TProvided>] extends [never] ? [options?: LambderCallOptions & {
+    guardInputs?: Partial<GuardInputsOf<TContract[TApiName]>>;
+}] : [
+    options: LambderCallOptions & {
+        guardInputs: RemainingGuardInputs<TContract[TApiName], TProvided> & Partial<GuardInputsOf<TContract[TApiName]>>;
+    }
+] : [options?: LambderCallOptions];
 type VoidFunction = () => void | Promise<void>;
 type FetchTracker = {
     apiName: string;
@@ -79,7 +117,9 @@ export type LambderCallOptions = {
     /**
      * Values for the API's guardInput-mode guards, keyed by guard name; sent
      * beside the payload and consumed by the guards before validation. The
-     * typed contract makes this REQUIRED for APIs that declare such guards.
+     * typed contract makes this REQUIRED for APIs that declare such guards,
+     * except the guards a guardInputsProvider covers (these merge on top of
+     * the provider's values).
      */
     guardInputs?: Record<string, unknown>;
     /**
@@ -102,7 +142,31 @@ export type LambderCallOptions = {
     fetchStartedHandler?: FetchStartEventHandler;
     fetchEndedHandler?: FetchEndEventHandler;
 };
-export default class LambderCaller<TContract extends ApiContractShape = any> {
+type LambderCallerBaseOptions = {
+    apiPath: string;
+    apiVersion?: string;
+    isCorsEnabled: boolean;
+    /** Default per-request timeout in ms (none unless set; API Gateway caps around 29s, so ~30000 is a sensible value). Overridable per call. */
+    timeoutMs?: number;
+    versionExpiredHandler?: VoidFunction;
+    sessionExpiredHandler?: VoidFunction;
+    messageHandler?: MessageHandler;
+    errorMessageHandler?: MessageHandler;
+    notAuthorizedHandler?: VoidFunction;
+    errorHandler?: ErrorHandler;
+    fetchStartedHandler?: FetchStartEventHandler;
+    fetchEndedHandler?: FetchEndEventHandler;
+    apiInputValidationErrorHandler?: ValidationErrorHandler;
+    /** Must mirror the server's session cookie Domain, otherwise expired cookies cannot be cleared. */
+    sessionCookieDomain?: string | ((hostname: string) => string | undefined | null);
+};
+/** Constructor options: the base options plus guardInputsProvider, mandatory once TProvided names guards. */
+export type LambderCallerOptions<TContract, TProvided extends string = never> = LambderCallerBaseOptions & GuardInputsProviderOption<TContract, TProvided>;
+/**
+ * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
+ * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
+ */
+export default class LambderCaller<TContract extends ApiContractShape = any, TProvidedGuards extends string = never> {
     private isCorsEnabled;
     private apiPath;
     private apiVersion?;
@@ -118,27 +182,11 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
     private apiInputValidationErrorHandler?;
     private fetchStartedHandler?;
     private fetchEndedHandler?;
+    private guardInputsProvider?;
     private sessionTokenCookieKey;
     private sessionCsrfCookieKey;
     private sessionCookieDomain?;
-    constructor({ apiPath, apiVersion, isCorsEnabled, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, }: {
-        apiPath: string;
-        apiVersion?: string;
-        isCorsEnabled: boolean;
-        /** Default per-request timeout in ms (none unless set; API Gateway caps around 29s, so ~30000 is a sensible value). Overridable per call. */
-        timeoutMs?: number;
-        versionExpiredHandler?: VoidFunction;
-        sessionExpiredHandler?: VoidFunction;
-        messageHandler?: MessageHandler;
-        errorMessageHandler?: MessageHandler;
-        notAuthorizedHandler?: VoidFunction;
-        errorHandler?: ErrorHandler;
-        fetchStartedHandler?: FetchStartEventHandler;
-        fetchEndedHandler?: FetchEndEventHandler;
-        apiInputValidationErrorHandler?: ValidationErrorHandler;
-        /** Must mirror the server's session cookie Domain, otherwise expired cookies cannot be cleared. */
-        sessionCookieDomain?: string | ((hostname: string) => string | undefined | null);
-    });
+    constructor(options: LambderCallerOptions<TContract, TProvidedGuards>);
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
     /**
      * A self-rotating idempotency key for a component or form that performs
@@ -171,8 +219,8 @@ export default class LambderCaller<TContract extends ApiContractShape = any> {
      * Full-fidelity call: resolves to a discriminated LambderApiOutcome
      * instead of collapsing every failure to null. Never throws.
      */
-    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<LambderApiOutcome<TOutput>>;
+    apiOutcome<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName, TProvidedGuards>): Promise<LambderApiOutcome<TOutput>>;
     /** Payload on success, null/undefined otherwise (indistinguishable from a null payload; prefer apiOutcome() when that matters). */
-    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName>): Promise<TOutput | null | undefined>;
+    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, ...rest: CallOptionsArg<TContract, TApiName, TProvidedGuards>): Promise<TOutput | null | undefined>;
 }
 export {};

package/dist/client/LambderCaller.js

@@ -1,4 +1,8 @@
 import Cookies from 'js-cookie';
+/**
+ * @typeParam TContract - The API contract, for typed names, payloads and guard inputs.
+ * @typeParam TProvidedGuards - Guard names guardInputsProvider covers; those APIs' options argument becomes optional.
+ */
 export default class LambderCaller {
     isCorsEnabled;
     apiPath;
@@ -15,10 +19,14 @@ export default class LambderCaller {
     apiInputValidationErrorHandler;
     fetchStartedHandler;
     fetchEndedHandler;
+    guardInputsProvider;
     sessionTokenCookieKey = "LMDRSESSIONTKID";
     sessionCsrfCookieKey = "LMDRSESSIONCSTK";
     sessionCookieDomain;
-    constructor({ apiPath, apiVersion, isCorsEnabled = false, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, }) {
+    constructor(options) {
+        // The conditional provider option is resolved per instantiation;
+        // inside the class it is read through the plain shape.
+        const { apiPath, apiVersion, isCorsEnabled = false, timeoutMs, versionExpiredHandler, sessionExpiredHandler, messageHandler, errorMessageHandler, notAuthorizedHandler, errorHandler, fetchStartedHandler, fetchEndedHandler, apiInputValidationErrorHandler, sessionCookieDomain, guardInputsProvider, } = options;
         this.apiPath = apiPath ?? "/api";
         this.apiVersion = apiVersion;
         this.isCorsEnabled = isCorsEnabled;
@@ -33,6 +41,7 @@ export default class LambderCaller {
         this.apiInputValidationErrorHandler = apiInputValidationErrorHandler;
         this.fetchStartedHandler = fetchStartedHandler;
         this.fetchEndedHandler = fetchEndedHandler;
+        this.guardInputsProvider = guardInputsProvider;
     }
     ;
     setSessionCookieKey(sessionTokenCookieKey, sessionCsrfCookieKey) {
@@ -159,6 +168,13 @@ export default class LambderCaller {
             const version = this.apiVersion;
             const token = Cookies.get(this.sessionCsrfCookieKey) || "";
             const siteHost = window.location.hostname;
+            // Provider values underneath, per-call values on top.
+            const providedGuardInputs = this.guardInputsProvider
+                ? await this.guardInputsProvider(apiName)
+                : undefined;
+            const guardInputs = providedGuardInputs !== undefined || options?.guardInputs !== undefined
+                ? { ...providedGuardInputs, ...options?.guardInputs }
+                : undefined;
             let res;
             try {
                 res = await fetch(this.apiPath, {
@@ -170,7 +186,7 @@ export default class LambderCaller {
                     headers: { 'Content-Type': 'application/json', ...(headers || {}) },
                     body: JSON.stringify({
                         apiName, version, token, siteHost, payload,
-                        ...(options?.guardInputs !== undefined ? { guardInputs: options.guardInputs } : {}),
+                        ...(guardInputs !== undefined ? { guardInputs } : {}),
                         ...(options?.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
                     }),
                     ...(signal ? { signal } : {}),

package/dist/client.d.ts

@@ -7,7 +7,7 @@
  * the root entry (`"lambder"`) is the server surface.
  */
 export { default as LambderCaller } from "./client/LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope, } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, } from "./client/LambderCaller.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";

package/dist/core/Lambder.d.ts

@@ -5,7 +5,8 @@ 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, type LambderSessionCompressionConfig } from "../session/LambderSessionManager.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";
@@ -95,7 +96,7 @@ export type LambderSessionOptions<TSessionData = any> = {
      * 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;
+    compression?: LambderCompressionOption;
 };
 /**
  * Everything an instance is configured with, in ONE declaration: base
@@ -109,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. */
@@ -193,11 +194,13 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
     setSessionExpiredRouteHandler(handler: FallbackHandlerFunction): this;
     /**
      * Terminal public-file layer. Runs only when no route matched, so it can
-     * never shadow routes registered after it. Serves real files under
-     * publicPath (traversal-safe, mime-typed, memory-cached, immutable-cache
-     * heuristic for content-hashed assets); when the file does not exist the
-     * request falls through to setRouteFallbackHandler, where the app decides
-     * what remains (e.g. render an app shell with res.templateFile).
+     * never shadow routes registered after it. Serves files from `source`
+     * (default: the publicPath folder; also LambderS3FileSource for S3 and
+     * R2, or any LambderPublicFileSource), traversal-safe, mime-typed,
+     * memory-cached, with the immutable-cache heuristic for content-hashed
+     * assets; when the source has no such file the request falls through to
+     * setRouteFallbackHandler, where the app decides what remains (e.g.
+     * render an app shell with res.templateFile).
      */
     servePublicFiles(options?: LambderPublicFilesOptions): this;
     /**

package/dist/core/Lambder.js

@@ -5,7 +5,7 @@ import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController from "../session/LambderSessionController.js";
-import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
+import { LambderPublicFilesHandler, LambderLocalFileSource } from "./LambderPublicFiles.js";
 import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.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,
         };
@@ -128,14 +129,17 @@ export default class Lambder {
     }
     /**
      * Terminal public-file layer. Runs only when no route matched, so it can
-     * never shadow routes registered after it. Serves real files under
-     * publicPath (traversal-safe, mime-typed, memory-cached, immutable-cache
-     * heuristic for content-hashed assets); when the file does not exist the
-     * request falls through to setRouteFallbackHandler, where the app decides
-     * what remains (e.g. render an app shell with res.templateFile).
+     * never shadow routes registered after it. Serves files from `source`
+     * (default: the publicPath folder; also LambderS3FileSource for S3 and
+     * R2, or any LambderPublicFileSource), traversal-safe, mime-typed,
+     * memory-cached, with the immutable-cache heuristic for content-hashed
+     * assets; when the source has no such file the request falls through to
+     * setRouteFallbackHandler, where the app decides what remains (e.g.
+     * render an app shell with res.templateFile).
      */
     servePublicFiles(options = {}) {
-        this.publicFilesHandler = new LambderPublicFilesHandler(this.publicPath, options);
+        const source = options.source ?? new LambderLocalFileSource({ root: this.publicPath });
+        this.publicFilesHandler = new LambderPublicFilesHandler(source, options);
         return this;
     }
     /**

package/dist/core/LambderPublicFiles.d.ts

@@ -1,14 +1,36 @@
 import type { LambderRenderContext } from "./LambderContext.js";
 import { LambderResponse } from "./LambderResponse.js";
+/** A file a source serves: its bytes, and its mime type when the source knows it (otherwise resolved from the extension). */
+export type LambderPublicFile = {
+    body: Buffer;
+    mimeType?: string;
+};
+/**
+ * Where servePublicFiles gets its files. Implement `read` over any backing
+ * store: LambderLocalFileSource (a folder, the default), LambderS3FileSource
+ * (S3, or R2 and other S3-compatible stores), or your own. The handler does
+ * the rest for every source: traversal check, memory cache, mime fallback
+ * from the extension, Cache-Control, ETag and compression.
+ */
+export interface LambderPublicFileSource {
+    /**
+     * The file at a relative path (no leading slash, no ".." segments: the
+     * handler rejects those before calling), or null when there is no such
+     * file, which lets the request fall through to the route fallback.
+     */
+    read(relativePath: string): Promise<LambderPublicFile | null>;
+}
 export type LambderPublicFilesOptions = {
+    /** Where files come from. Default: LambderLocalFileSource over publicPath. */
+    source?: LambderPublicFileSource;
     /**
-     * Map the request to a file path under publicPath (app-owned logic, e.g.
-     * per-tenant roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
+     * Map the request to a file path (app-owned logic, e.g. per-tenant
+     * roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
      * null/undefined to skip. Default: (ctx) => ctx.path.
      */
     path?: (ctx: LambderRenderContext) => string | null | undefined;
-    /** Cache-Control for served files. Default: "public, max-age=3600". */
-    cacheControl?: string | ((ctx: LambderRenderContext, filePath: string) => string);
+    /** Cache-Control for served files; the function receives the relative file path. Default: "public, max-age=3600". */
+    cacheControl?: string | ((ctx: LambderRenderContext, relativePath: string) => string);
     /** Filenames matching this get immutableCacheControl. Default: content-hash heuristic. Set false to disable. */
     immutablePattern?: RegExp | false;
     /** Default: "public, max-age=31536000, immutable". */
@@ -24,24 +46,34 @@ export type LambderPublicFilesOptions = {
      */
     compress?: boolean | "auto" | ((ctx: LambderRenderContext) => boolean | "auto");
 };
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root. The default
+ * source of servePublicFiles, over publicPath.
+ */
+export declare class LambderLocalFileSource implements LambderPublicFileSource {
+    private root;
+    constructor({ root }: {
+        root: string;
+    });
+    read(relativePath: string): Promise<LambderPublicFile | null>;
+}
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * after it. Serves real files under publicPath (traversal-safe, mime-typed,
+ * after it. Serves files from its source (traversal-safe, mime-typed,
  * memory-cached, immutable-cache heuristic for content-hashed assets) and
- * falls through to the route fallback when the file does not exist.
+ * falls through to the route fallback when the source has no such file.
  */
 export declare class LambderPublicFilesHandler {
-    private publicPath;
+    private source;
     private options;
     private fileCache;
     private fileCacheBytes;
-    constructor(publicPath: string, options: LambderPublicFilesOptions);
+    constructor(source: LambderPublicFileSource, options: LambderPublicFilesOptions);
     /** Serve the mapped file, or return null to fall through. */
     handle(ctx: LambderRenderContext): Promise<LambderResponse | null>;
-    /** Join base+target and require the result to stay under base. */
-    private resolveSafe;
-    /** Read a file, caching small files in memory for warm invocations. */
-    private readFileCached;
+    /** Read from the source, caching small files in memory for warm invocations. */
+    private readCached;
     private cacheControlFor;
 }