lambder 4.3.2 → 4.5.1

package/Readme.md

@@ -2,6 +2,16 @@
 
 Lambder is a highly opinionated dynamic serverless framework designed to facilitate the management and implementation of routes and APIs within AWS Lambda functions, specifically tailored for TypeScript projects. It provides a streamlined approach to handling HTTP requests, managing sessions, and defining API routes, making serverless application development more intuitive and structured.
 
+**New in 4.5:**
+
+- **`files` at creation replaces `publicPath`** (and `servePublicFiles({ source })`): one `LambderFileSource` configured once, `files: new LambderLocalFileSource({ root: path.resolve("./public") })` for the folder bundled with the deployment, `new LambderS3FileSource({...})` for S3 or R2, or your own `{ read(relativePath) }`. The instance owns one reader over it (`lambder.files`): path rule, in-memory file cache and compiled-template cache in one place, shared by `servePublicFiles`, `serveIndexHtml`, `res.file` and `res.templateFile`, so a build hosted from a bucket serves its index.html and templates from the bucket too, cached the same way as its assets. The cache is tuned or disabled beside the source, `files: { source, memoryCache }`, and `memoryCache` leaves `servePublicFiles`; `res.file` loses its SPA-era `fallback` option (the fallback chain replaced it).
+
+**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.
@@ -86,7 +96,7 @@ would silently widen the inferred policy types, which is why the curried
 creator is the canonical entry.
 
 ```typescript
-import { initLambder } from 'lambder';
+import { initLambder, LambderLocalFileSource } from 'lambder';
 import { z } from 'zod';
 import * as path from 'path';
 
@@ -94,7 +104,7 @@ interface SessionData { userId: string; }
 
 const lambder = initLambder<SessionData>().create({
     apiPath: "/api",
-    publicPath: path.resolve(`./public`),
+    files: new LambderLocalFileSource({ root: path.resolve(`./public`) }),
     session: {
         tableName: "website-session",
         tableRegion: "us-east-1",
@@ -160,8 +170,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 the files source (see "Public file sources"
+    // below). 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).
@@ -209,7 +220,7 @@ For larger applications, split your APIs into separate modules:
 ```typescript
 // user-api.ts
 import { z } from "zod";
-import Lambder from "lambder";
+import Lambder, { LambderLocalFileSource } from "lambder";
 
 export const userApi = <T>(l: Lambder<T>) => {
     return l
@@ -230,7 +241,7 @@ export const userApi = <T>(l: Lambder<T>) => {
 // index.ts
 import { userApi } from "./user-api";
 
-const lambder = new Lambder({ publicPath: './public' })
+const lambder = new Lambder({ files: new LambderLocalFileSource({ root: './public' }) })
     .use(userApi);
 
 export type ApiContractType = typeof lambder.ApiContract;
@@ -359,6 +370,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`)
 
@@ -389,6 +401,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)
@@ -432,6 +445,37 @@ 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
+
+The `files` option at creation is a `LambderFileSource`, an object with one method, `read(relativePath)`, returning `{ body, mimeType? }` or `null`. The instance owns one reader over it, `lambder.files`, and `servePublicFiles`, `serveIndexHtml`, `res.file` and `res.templateFile` all go through that reader, which does everything else for every source: traversal check, in-memory file cache for warm invocations (default 32MB, 2MB per file), compiled-template cache, mime fallback from the extension. Cache-Control (immutable for content-hashed names), ETag and compression are applied by the serving slot and the response pipeline. Built in:
+
+```typescript
+// A folder, typically the build output bundled with the deployment.
+initLambder().create({ files: new LambderLocalFileSource({ root: path.resolve("./public") }) });
+
+// S3. @aws-sdk/client-s3 is an optional peer dependency, loaded on first read.
+initLambder().create({
+    files: 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.
+initLambder().create({
+    files: new LambderS3FileSource({
+        bucket: "myapp-web",
+        clientConfig: { region: "auto", endpoint: "https://<account>.r2.cloudflarestorage.com", credentials: { accessKeyId, secretAccessKey } },
+    }),
+});
+
+// Anything else: implement read().
+initLambder().create({ files: { read: async (relativePath) => myStore.get(relativePath) } });
+
+// The in-memory file cache, tuned or off, beside any source.
+initLambder().create({ files: { source: new LambderS3FileSource({ bucket: "myapp-web" }), memoryCache: { maxBytes: 64_000_000, maxFileBytes: 4_000_000 } } });
+initLambder().create({ files: { source: new LambderLocalFileSource({ root }), memoryCache: false } });
+```
+
+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();
@@ -772,7 +816,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

@@ -9,6 +9,7 @@ import { type LambderSessionDataRefreshConfig } from "../session/LambderSessionM
 import type { LambderCompressionOption } from "../stores/LambderDdbCompression.js";
 import LambderSessionController, { type LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import { type LambderPublicFilesOptions } from "./LambderPublicFiles.js";
+import { LambderFiles, type LambderFilesOption } from "./LambderFiles.js";
 import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf } from "../policies/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderRateLimitOption } from "../policies/LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "../policies/LambderApiIdempotency.js";
@@ -107,7 +108,14 @@ export type LambderSessionOptions<TSessionData = any> = {
  * instance type ever needs a name.
  */
 export type LambderCreateOptions<TSessionData = any> = {
-    publicPath?: string;
+    /**
+     * Where the app's files come from, for servePublicFiles, serveIndexHtml,
+     * res.file and res.templateFile: a LambderLocalFileSource over a folder
+     * (the build output bundled with the deployment), a LambderS3FileSource
+     * (S3, R2), or any LambderFileSource; or `{ source, memoryCache }` to
+     * tune or disable the in-memory file cache. Required by those features.
+     */
+    files?: LambderFilesOption;
     apiPath?: string;
     apiVersion?: string;
     /** Automatic gzip for compressible responses. `true` (the default) is `{ minBytes: 860 }`; `false` disables it. */
@@ -153,7 +161,8 @@ export type LambderCreateOptions<TSessionData = any> = {
 export default class Lambder<TSessionData = any, _TContract extends Record<string, any> = {}, _TRateLimitPolicies extends Record<string, LambderApiRateLimitPolicyConfig> = {}, _TGuards extends Record<string, any> = {}, _TIdempotencyEnabled extends boolean = false> {
     apiPath: string;
     apiVersion: null | string;
-    publicPath: string;
+    /** The instance's file reader (source + caches), or null without the files option. */
+    files: LambderFiles | null;
     /**
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
@@ -194,11 +203,12 @@ 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 the `files`
+     * source configured at creation, 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;
     /**
@@ -207,8 +217,8 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * gone; everything left is an app route (option `skipFilePaths` opts back
      * into 404ing dotted paths). Only configured methods reach it, default
      * GET/HEAD. Gated-out requests fall through to setRouteFallbackHandler.
-     * Without a handler, publicPath/index.html is served via res.templateFile
-     * (markers optional) with no-cache.
+     * Without a handler, index.html from the files source is served via
+     * res.templateFile (markers optional) with no-cache.
      */
     serveIndexHtml(handler?: FallbackHandlerFunction, options?: LambderIndexHtmlOptions): this;
     /** Apply the serveIndexHtml gates; null means fall through. */

package/dist/core/Lambder.js

@@ -6,6 +6,7 @@ import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController from "../session/LambderSessionController.js";
 import { LambderPublicFilesHandler } from "./LambderPublicFiles.js";
+import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiError, LAMBDER_REFUSAL_CODES } from "../shared/LambderApiError.js";
 import { LambderApiPolicyEngine } from "../policies/LambderApiPolicies.js";
 import { createContext, isV2HttpEvent } from "./LambderContext.js";
@@ -33,7 +34,8 @@ import { createContext, isV2HttpEvent } from "./LambderContext.js";
 export default class Lambder {
     apiPath;
     apiVersion;
-    publicPath;
+    /** The instance's file reader (source + caches), or null without the files option. */
+    files;
     /**
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
@@ -66,7 +68,7 @@ export default class Lambder {
     sessionTokenCookieKey = "LMDRSESSIONTKID";
     sessionCsrfCookieKey = "LMDRSESSIONCSTK";
     constructor(options = {}) {
-        this.publicPath = options.publicPath || "/incorrect-path-not-found";
+        this.files = options.files ? new LambderFiles(options.files) : null;
         this.apiPath = options.apiPath ?? "/api";
         this.apiVersion = options.apiVersion ?? null;
         this.finalizeOptions = {
@@ -129,14 +131,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 the `files`
+     * source configured at creation, 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);
+        if (!this.files)
+            throw new Error("servePublicFiles requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))");
+        this.publicFilesHandler = new LambderPublicFilesHandler(this.files, options);
         return this;
     }
     /**
@@ -145,8 +150,8 @@ export default class Lambder {
      * gone; everything left is an app route (option `skipFilePaths` opts back
      * into 404ing dotted paths). Only configured methods reach it, default
      * GET/HEAD. Gated-out requests fall through to setRouteFallbackHandler.
-     * Without a handler, publicPath/index.html is served via res.templateFile
-     * (markers optional) with no-cache.
+     * Without a handler, index.html from the files source is served via
+     * res.templateFile (markers optional) with no-cache.
      */
     serveIndexHtml(handler, options = {}) {
         this.indexHtmlConfig = { handler: handler ?? null, options };
@@ -328,7 +333,7 @@ export default class Lambder {
     }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
-            publicPath: this.publicPath,
+            files: this.files,
             apiVersion: this.apiVersion,
             ctx,
         });
@@ -336,7 +341,7 @@ export default class Lambder {
     ;
     getResolver(ctx) {
         return new LambderResolver({
-            publicPath: this.publicPath,
+            files: this.files,
             apiVersion: this.apiVersion,
             ctx,
         });

package/dist/core/LambderFiles.d.ts

@@ -0,0 +1,85 @@
+import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+/** A file a source serves: its bytes, and its mime type when the source knows it (otherwise resolved from the extension). */
+export type LambderFile = {
+    body: Buffer;
+    mimeType?: string;
+};
+/**
+ * Where an app's files come from: the `files` option at creation, read by
+ * servePublicFiles, serveIndexHtml, res.file and res.templateFile alike,
+ * through the instance's one reader (LambderFiles). Implement `read` over
+ * any backing store: LambderLocalFileSource (a folder), LambderS3FileSource
+ * (S3, or R2 and other S3-compatible stores), or your own. The reader does
+ * the rest for every source: traversal check, memory cache, mime fallback
+ * from the extension.
+ */
+export interface LambderFileSource {
+    /**
+     * The file at a relative path (no leading slash, no ".." segments: the
+     * reader rejects those before calling), or null when there is no such
+     * file, which lets a request fall through to the route fallback.
+     */
+    read(relativePath: string): Promise<LambderFile | null>;
+}
+/** In-memory cache of files for warm invocations. Default: { maxBytes: 32MB, maxFileBytes: 2MB }. false disables it. */
+export type LambderFileMemoryCacheOption = false | {
+    maxBytes?: number;
+    maxFileBytes?: number;
+};
+/** The `files` option at creation: a source, or a source with its memory cache tuned or off. */
+export type LambderFilesOption = LambderFileSource | {
+    source: LambderFileSource;
+    memoryCache?: LambderFileMemoryCacheOption;
+};
+/** A file as the reader hands it out: path normalized, mime type resolved. */
+export type LambderReadFile = {
+    body: Buffer;
+    mimeType: string;
+    relativePath: string;
+};
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root.
+ */
+export declare class LambderLocalFileSource implements LambderFileSource {
+    private root;
+    constructor({ root }: {
+        root: string;
+    });
+    read(relativePath: string): Promise<LambderFile | null>;
+}
+/**
+ * The path a source is asked for: leading slash stripped, traversal
+ * rejected; null for a path that names no file (empty, or a directory).
+ */
+export declare const toRelativePath: (target: string) => string | null;
+/**
+ * The app's file reader, owned by the Lambder instance: one source, one
+ * path rule, one memory cache and one compiled-template cache, shared by
+ * every feature that reads files. Both caches live as long as the instance,
+ * i.e. across warm invocations.
+ */
+export declare class LambderFiles {
+    private source;
+    private cache;
+    private cacheBytes;
+    private maxBytes;
+    private maxFileBytes;
+    private templates;
+    constructor(option: LambderFilesOption);
+    /**
+     * The file at a request or handler path (leading slash optional), mime
+     * type resolved; null when the path is invalid or the source has none.
+     */
+    read(path: string): Promise<LambderReadFile | null>;
+    /**
+     * The compiled template for an HTML file, compiled once per instance.
+     * A missing file throws: it is a server-side configuration error, not a
+     * client 404.
+     */
+    template(path: string, options?: {
+        htmlVirtualSlots?: boolean;
+    }): Promise<LambderTemplatingEngine>;
+    /** Cache small files within the byte budget, evicting the oldest entries first. */
+    private remember;
+}