lambder 4.4.1 → 4.5.1

package/Readme.md

@@ -2,6 +2,10 @@
 
 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.
@@ -92,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';
 
@@ -100,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",
@@ -166,9 +170,9 @@ lambder
     .addRoute({ path: "/stripe-webhook", method: "POST" }, (ctx, res) => {
         return res.json({ received: true });
     })
-    // 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.
+    // 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).
@@ -216,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
@@ -237,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;
@@ -443,27 +447,31 @@ Lambder has no SPA-specific machinery; hosting a frontend build is a recipe buil
 
 #### 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:
+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
-// Default: the publicPath folder bundled with the deployment.
-lambder.servePublicFiles();
+// 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.
-lambder.servePublicFiles({
-    source: new LambderS3FileSource({ bucket: "myapp-web", prefix: "v42/", clientConfig: { region: "eu-central-1" } }),
+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.
-lambder.servePublicFiles({
-    source: new LambderS3FileSource({
+initLambder().create({
+    files: 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) } });
+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.

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,9 +203,8 @@ 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 files from `source`
-     * (default: the publicPath folder; also LambderS3FileSource for S3 and
-     * R2, or any LambderPublicFileSource), traversal-safe, mime-typed,
+     * 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.
@@ -209,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

@@ -5,7 +5,8 @@ import { compileRouteMatcher } from "./LambderRouting.js";
 import { applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController from "../session/LambderSessionController.js";
-import { LambderPublicFilesHandler, LambderLocalFileSource } from "./LambderPublicFiles.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,17 +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 files from `source`
-     * (default: the publicPath folder; also LambderS3FileSource for S3 and
-     * R2, or any LambderPublicFileSource), traversal-safe, mime-typed,
+     * 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 = {}) {
-        const source = options.source ?? new LambderLocalFileSource({ root: this.publicPath });
-        this.publicFilesHandler = new LambderPublicFilesHandler(source, 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;
     }
     /**
@@ -148,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 };
@@ -331,7 +333,7 @@ export default class Lambder {
     }
     getResponseBuilder(ctx) {
         return new LambderResponseBuilder({
-            publicPath: this.publicPath,
+            files: this.files,
             apiVersion: this.apiVersion,
             ctx,
         });
@@ -339,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;
+}

package/dist/core/LambderFiles.js

@@ -0,0 +1,116 @@
+import mimeTypeResolver from "mime-types";
+import { getFS, getPath } from "../shared/node-polyfills.js";
+import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
+const DEFAULT_MEMORY_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+const DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES = 2 * 1024 * 1024;
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root.
+ */
+export class LambderLocalFileSource {
+    root;
+    constructor({ root }) {
+        this.root = root;
+    }
+    async read(relativePath) {
+        const fs = await getFS();
+        const path = await getPath();
+        if (!fs || !path)
+            throw new Error("LambderLocalFileSource requires a Node.js environment.");
+        const base = path.resolve(this.root);
+        const absolute = path.resolve(base, relativePath);
+        if (absolute !== base && !absolute.startsWith(base + path.sep))
+            return null;
+        const stat = await fs.promises.stat(absolute).catch(() => null);
+        if (!stat?.isFile())
+            return null;
+        return { body: await fs.promises.readFile(absolute) };
+    }
+}
+/**
+ * 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 const toRelativePath = (target) => {
+    if (target.split("/").some((segment) => segment === ".."))
+        return null;
+    const relative = target.startsWith("/") ? target.slice(1) : target;
+    if (relative === "" || relative.endsWith("/"))
+        return null;
+    return relative;
+};
+/**
+ * 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 class LambderFiles {
+    source;
+    cache;
+    cacheBytes = 0;
+    maxBytes;
+    maxFileBytes;
+    templates = new Map();
+    constructor(option) {
+        const { source, memoryCache } = "source" in option ? option : { source: option, memoryCache: undefined };
+        this.source = source;
+        this.cache = memoryCache === false ? null : new Map();
+        this.maxBytes = memoryCache === false ? 0 : (memoryCache?.maxBytes ?? DEFAULT_MEMORY_CACHE_MAX_BYTES);
+        this.maxFileBytes = memoryCache === false ? 0 : (memoryCache?.maxFileBytes ?? DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES);
+    }
+    /**
+     * 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.
+     */
+    async read(path) {
+        const relativePath = toRelativePath(path);
+        if (relativePath === null)
+            return null;
+        const cached = this.cache?.get(relativePath);
+        if (cached)
+            return cached;
+        const file = await this.source.read(relativePath);
+        if (!file)
+            return null;
+        const entry = {
+            body: file.body,
+            mimeType: file.mimeType || mimeTypeResolver.lookup(relativePath) || "application/octet-stream",
+            relativePath,
+        };
+        this.remember(entry);
+        return entry;
+    }
+    /**
+     * 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.
+     */
+    async template(path, options = {}) {
+        const key = `${toRelativePath(path)}|${options.htmlVirtualSlots ? "v" : ""}`;
+        const cached = this.templates.get(key);
+        if (cached)
+            return cached;
+        const file = await this.read(path);
+        if (!file)
+            throw new Error(`templateFile: file not found in the files source: ${path}`);
+        const template = new LambderTemplatingEngine(file.body.toString("utf8"), { htmlVirtualSlots: options.htmlVirtualSlots });
+        this.templates.set(key, template);
+        return template;
+    }
+    /** Cache small files within the byte budget, evicting the oldest entries first. */
+    remember(entry) {
+        if (!this.cache || entry.body.length > this.maxFileBytes)
+            return;
+        for (const [key, value] of this.cache) {
+            if (this.cacheBytes + entry.body.length <= this.maxBytes)
+                break;
+            this.cache.delete(key);
+            this.cacheBytes -= value.body.length;
+        }
+        if (this.cacheBytes + entry.body.length <= this.maxBytes) {
+            this.cache.set(entry.relativePath, entry);
+            this.cacheBytes += entry.body.length;
+        }
+    }
+}

package/dist/core/LambderPublicFiles.d.ts

@@ -1,28 +1,8 @@
 import type { LambderRenderContext } from "./LambderContext.js";
+import type { LambderFiles } from "./LambderFiles.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>;
-}
+/** Per-registration policy of servePublicFiles: how a request maps to a file and how the response is cached. */
 export type LambderPublicFilesOptions = {
-    /** Where files come from. Default: LambderLocalFileSource over publicPath. */
-    source?: LambderPublicFileSource;
     /**
      * Map the request to a file path (app-owned logic, e.g. per-tenant
      * roots: (ctx) => `${brand(ctx.host)}${ctx.path}`). Return
@@ -35,45 +15,25 @@ export type LambderPublicFilesOptions = {
     immutablePattern?: RegExp | false;
     /** Default: "public, max-age=31536000, immutable". */
     immutableCacheControl?: string;
-    /** In-memory cache of files for warm invocations. Default: { maxBytes: 32MB, maxFileBytes: 2MB }. Set false to disable. */
-    memoryCache?: false | {
-        maxBytes?: number;
-        maxFileBytes?: number;
-    };
     /**
      * Compression per file: "auto" (default: compressible mime + size threshold),
      * true/false, or a function, e.g. (ctx) => /\.(css|js|svg)$/.test(ctx.path).
      */
     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 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 source has no such file.
+ * after it. Serves files through the instance's reader (traversal-safe,
+ * mime-typed, memory-cached) with the immutable-cache heuristic for
+ * content-hashed assets, and falls through to the route fallback when the
+ * source has no such file.
  */
 export declare class LambderPublicFilesHandler {
-    private source;
+    private files;
     private options;
-    private fileCache;
-    private fileCacheBytes;
-    constructor(source: LambderPublicFileSource, options: LambderPublicFilesOptions);
+    constructor(files: LambderFiles, options: LambderPublicFilesOptions);
     /** Serve the mapped file, or return null to fall through. */
     handle(ctx: LambderRenderContext): Promise<LambderResponse | null>;
-    /** Read from the source, caching small files in memory for warm invocations. */
-    private readCached;
     private cacheControlFor;
 }

package/dist/core/LambderPublicFiles.js

@@ -1,61 +1,22 @@
-import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "../shared/node-polyfills.js";
 import { LambderResponse } from "./LambderResponse.js";
 // Content-hashed build outputs (Vite/webpack/Rollup): a [-.] separated run of
 // 8+ hash chars containing at least one digit, before the extension.
 const DEFAULT_IMMUTABLE_PATTERN = /[-.](?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
 const DEFAULT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 const DEFAULT_CACHE_CONTROL = "public, max-age=3600";
-const DEFAULT_MEMORY_CACHE_MAX_BYTES = 32 * 1024 * 1024;
-const DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES = 2 * 1024 * 1024;
-/**
- * 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 class LambderLocalFileSource {
-    root;
-    constructor({ root }) {
-        this.root = root;
-    }
-    async read(relativePath) {
-        const fs = await getFS();
-        const path = await getPath();
-        if (!fs || !path)
-            throw new Error("LambderLocalFileSource requires a Node.js environment.");
-        const base = path.resolve(this.root);
-        const absolute = path.resolve(base, relativePath);
-        if (absolute !== base && !absolute.startsWith(base + path.sep))
-            return null;
-        const stat = await fs.promises.stat(absolute).catch(() => null);
-        if (!stat?.isFile())
-            return null;
-        return { body: await fs.promises.readFile(absolute) };
-    }
-}
-/** Strip the leading slash and reject traversal; null for a path that names no file (empty, or a directory). */
-const toRelativePath = (target) => {
-    if (target.split("/").some((segment) => segment === ".."))
-        return null;
-    const relative = target.startsWith("/") ? target.slice(1) : target;
-    if (relative === "" || relative.endsWith("/"))
-        return null;
-    return relative;
-};
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * 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 source has no such file.
+ * after it. Serves files through the instance's reader (traversal-safe,
+ * mime-typed, memory-cached) with the immutable-cache heuristic for
+ * content-hashed assets, and falls through to the route fallback when the
+ * source has no such file.
  */
 export class LambderPublicFilesHandler {
-    source;
+    files;
     options;
-    fileCache = new Map();
-    fileCacheBytes = 0;
-    constructor(source, options) {
-        this.source = source;
+    constructor(files, options) {
+        this.files = files;
         this.options = options;
     }
     /** Serve the mapped file, or return null to fall through. */
@@ -63,10 +24,7 @@ export class LambderPublicFilesHandler {
         const mappedPath = this.options.path ? this.options.path(ctx) : ctx.path;
         if (!mappedPath)
             return null;
-        const relativePath = toRelativePath(mappedPath);
-        if (relativePath === null)
-            return null;
-        const file = await this.readCached(relativePath);
+        const file = await this.files.read(mappedPath);
         if (!file)
             return null;
         const compressOption = this.options.compress;
@@ -75,44 +33,12 @@ export class LambderPublicFilesHandler {
             statusCode: 200,
             headers: {
                 "Content-Type": file.mimeType,
-                "Cache-Control": this.cacheControlFor(ctx, relativePath),
+                "Cache-Control": this.cacheControlFor(ctx, file.relativePath),
             },
             body: file.body,
             compress,
         });
     }
-    /** Read from the source, caching small files in memory for warm invocations. */
-    async readCached(relativePath) {
-        const cached = this.fileCache.get(relativePath);
-        if (cached)
-            return cached;
-        const file = await this.source.read(relativePath);
-        if (!file)
-            return null;
-        const entry = {
-            body: file.body,
-            mimeType: file.mimeType || mimeTypeResolver.lookup(relativePath) || "application/octet-stream",
-        };
-        const cacheConfig = this.options.memoryCache;
-        if (cacheConfig !== false) {
-            const maxBytes = cacheConfig?.maxBytes ?? DEFAULT_MEMORY_CACHE_MAX_BYTES;
-            const maxFileBytes = cacheConfig?.maxFileBytes ?? DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES;
-            if (entry.body.length <= maxFileBytes) {
-                // Evict oldest entries until the new file fits the budget.
-                for (const [key, value] of this.fileCache) {
-                    if (this.fileCacheBytes + entry.body.length <= maxBytes)
-                        break;
-                    this.fileCache.delete(key);
-                    this.fileCacheBytes -= value.body.length;
-                }
-                if (this.fileCacheBytes + entry.body.length <= maxBytes) {
-                    this.fileCache.set(relativePath, entry);
-                    this.fileCacheBytes += entry.body.length;
-                }
-            }
-        }
-        return entry;
-    }
     cacheControlFor(ctx, relativePath) {
         const cacheOption = this.options.cacheControl;
         if (typeof cacheOption === "function")

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,7 +1,8 @@
 import type { LambderRenderContext } from "./LambderContext.js";
+import type { LambderFiles } from "./LambderFiles.js";
 import { LambderResponse, type HttpStatusCode, type LambderHeadersInput } from "./LambderResponse.js";
 import { LambderSafeHtml } from "../shared/LambderHtml.js";
-import { type LambderTemplateData } from "./LambderTemplatingEngine.js";
+import type { LambderTemplateData } from "./LambderTemplatingEngine.js";
 import type { LambderApiResponseConfig } from "../shared/LambderApiContract.js";
 export type { LambderApiResponse, LambderApiResponseConfig } from "../shared/LambderApiContract.js";
 export type LambderResponseOptions = {
@@ -24,16 +25,17 @@ export type LambderRawResponseInit = {
     etag?: boolean | "auto";
 };
 export default class LambderResponseBuilder<TResponse = any> {
-    protected publicPath: string;
+    protected files: LambderFiles | null;
     protected apiVersion: string | null;
     protected ctx?: LambderRenderContext;
-    constructor({ publicPath, apiVersion, ctx }: {
-        publicPath: string;
+    constructor({ files, apiVersion, ctx }: {
+        files?: LambderFiles | null;
         apiVersion?: string | null;
         ctx?: LambderRenderContext;
     });
     private buildResponse;
-    private resolvePublicFilePath;
+    /** The instance's file reader, which res.file and res.templateFile need. */
+    private requireFiles;
     addHeader(key: string, value: string): void;
     setHeader(key: string, value: string | string[]): void;
     logToApiResponse(input: any): void;
@@ -47,15 +49,15 @@ export default class LambderResponseBuilder<TResponse = any> {
     redirect(url: string, statusCode?: HttpStatusCode, options?: LambderResponseOptions): LambderResponse;
     versionExpired(options?: LambderResponseOptions): LambderResponse;
     fileBase64(fileBase64: string, mimeType: string, options?: LambderResponseOptions): LambderResponse;
-    file(filePath: string, options?: LambderResponseOptions & {
-        fallback?: string;
-    }): Promise<LambderResponse>;
+    /** A file from the files source as a response; 404 when there is none. */
+    file(filePath: string, options?: LambderResponseOptions): Promise<LambderResponse>;
     /**
-     * Render an HTML file under publicPath through LambderTemplatingEngine
-     * (comment-based slots/conditionals) and return it as an HTML response.
-     * The compiled template is cached across warm invocations; a missing file
-     * throws (it is a server-side configuration error, not a client 404).
-     * Set htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
+     * Render an HTML file from the files source through
+     * LambderTemplatingEngine (comment-based slots/conditionals) and return
+     * it as an HTML response. The compiled template is cached on the
+     * instance across warm invocations; a missing file throws (it is a
+     * server-side configuration error, not a client 404). Set
+     * htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
      */
     templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
         htmlVirtualSlots?: boolean;

package/dist/core/LambderResponseBuilder.js

@@ -1,15 +1,10 @@
-import mimeTypeResolver from "mime-types";
-import { getFS, getPath } from "../shared/node-polyfills.js";
 import { LambderResponse } from "./LambderResponse.js";
-import { LambderTemplatingEngine } from "./LambderTemplatingEngine.js";
-// Compiled templates survive across requests (builder instances are per-request).
-const templateFileCache = new Map();
 export default class LambderResponseBuilder {
-    publicPath;
+    files;
     apiVersion;
     ctx;
-    constructor({ publicPath, apiVersion, ctx }) {
-        this.publicPath = publicPath;
+    constructor({ files, apiVersion, ctx }) {
+        this.files = files ?? null;
         this.apiVersion = apiVersion ?? null;
         this.ctx = ctx;
     }
@@ -30,25 +25,12 @@ export default class LambderResponseBuilder {
             response.setHeader("Cache-Control", options.cacheControl);
         return response;
     }
-    async resolvePublicFilePath(filePath) {
-        const fs = await getFS();
-        const path = await getPath();
-        if (!fs || !path)
-            return null;
-        const publicPath = path.resolve(this.publicPath);
-        const normalizedFilePath = filePath.startsWith('/') ? filePath.slice(1) : filePath;
-        const absolutePath = path.resolve(publicPath, normalizedFilePath);
-        if (absolutePath !== publicPath && !absolutePath.startsWith(publicPath + path.sep))
-            return null;
-        try {
-            const stat = await fs.promises.stat(absolutePath);
-            return stat.isFile() ? absolutePath : null;
-        }
-        catch {
-            return null;
-        }
+    /** The instance's file reader, which res.file and res.templateFile need. */
+    requireFiles(method) {
+        if (!this.files)
+            throw new Error(`${method} requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))`);
+        return this.files;
     }
-    ;
     addHeader(key, value) {
         if (!this.ctx)
             throw new Error(".addHeader function is not available within this hook");
@@ -130,41 +112,24 @@ export default class LambderResponseBuilder {
         return response;
     }
     ;
+    /** A file from the files source as a response; 404 when there is none. */
     async file(filePath, options) {
-        let resolvedPath = await this.resolvePublicFilePath(filePath);
-        let effectivePath = filePath;
-        if (!resolvedPath && options?.fallback) {
-            resolvedPath = await this.resolvePublicFilePath(options.fallback);
-            effectivePath = options.fallback;
-        }
-        if (!resolvedPath) {
+        const file = await this.requireFiles("res.file").read(filePath);
+        if (!file)
             return this.status404("File not found", { etag: false });
-        }
-        const fs = await getFS();
-        if (!fs)
-            return this.status404("File not found", { etag: false });
-        const body = await fs.promises.readFile(resolvedPath);
-        const mimeType = mimeTypeResolver.lookup(effectivePath) || "application/octet-stream";
-        return this.buildResponse(200, mimeType, body, options);
+        return this.buildResponse(200, file.mimeType, file.body, options);
     }
     ;
     /**
-     * Render an HTML file under publicPath through LambderTemplatingEngine
-     * (comment-based slots/conditionals) and return it as an HTML response.
-     * The compiled template is cached across warm invocations; a missing file
-     * throws (it is a server-side configuration error, not a client 404).
-     * Set htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
+     * Render an HTML file from the files source through
+     * LambderTemplatingEngine (comment-based slots/conditionals) and return
+     * it as an HTML response. The compiled template is cached on the
+     * instance across warm invocations; a missing file throws (it is a
+     * server-side configuration error, not a client 404). Set
+     * htmlVirtualSlots to expose "title"/"head" slots on marker-less files.
      */
     async templateFile(filePath, data, options) {
-        const resolvedPath = await this.resolvePublicFilePath(filePath);
-        if (!resolvedPath)
-            throw new Error(`templateFile: file not found under publicPath: ${filePath}`);
-        const cacheKey = `${resolvedPath}|${options?.htmlVirtualSlots ? "v" : ""}`;
-        let template = templateFileCache.get(cacheKey);
-        if (!template) {
-            template = await LambderTemplatingEngine.fromFile(resolvedPath, { htmlVirtualSlots: options?.htmlVirtualSlots });
-            templateFileCache.set(cacheKey, template);
-        }
+        const template = await this.requireFiles("res.templateFile").template(filePath, { htmlVirtualSlots: options?.htmlVirtualSlots });
         return this.buildResponse(200, "text/html; charset=utf-8", template.render(data), options);
     }
     ;

package/dist/core/LambderTemplatingEngine.d.ts

@@ -4,7 +4,7 @@ import { type LambderHtmlValue } from "../shared/LambderHtml.js";
  *
  * Fully standalone: it has no dependency on Lambder routing or file serving,
  * and can template any HTML: app shells, emails, error pages. res.templateFile
- * uses it internally to render HTML files from publicPath per request.
+ * uses it internally to render HTML files from the files source per request.
  *
  * Every construct is an HTML comment. That is the whole point: templates
  * survive HTML build pipelines (e.g. Vite) untouched, and are invisible in the

package/dist/index.d.ts

@@ -15,8 +15,10 @@ export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
 export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
 export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, LambderSessionOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./core/Lambder.js";
-export { LambderPublicFilesHandler, LambderLocalFileSource } from "./core/LambderPublicFiles.js";
-export type { LambderPublicFilesOptions, LambderPublicFileSource, LambderPublicFile } from "./core/LambderPublicFiles.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
+export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
+export type { LambderFileSource, LambderFile, LambderFilesOption, LambderFileMemoryCacheOption, LambderReadFile } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export type { LambderS3FileSourceOptions } from "./stores/LambderS3FileSource.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";

package/dist/index.js

@@ -15,7 +15,8 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 // Comment-based HTML templating engine (build-pipeline-safe slots and conditionals, standalone)
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 // Public file serving
-export { LambderPublicFilesHandler, LambderLocalFileSource } from "./core/LambderPublicFiles.js";
+export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export { LambderFiles, LambderLocalFileSource } from "./core/LambderFiles.js";
 export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 // DynamoDB-backed compressed cache (standalone, server-only)

package/dist/stores/LambderS3FileSource.d.ts

@@ -1,5 +1,5 @@
 import type { S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
-import type { LambderPublicFile, LambderPublicFileSource } from "../core/LambderPublicFiles.js";
+import type { LambderFile, LambderFileSource } from "../core/LambderFiles.js";
 export type LambderS3FileSourceOptions = {
     bucket: string;
     /** Literal key prefix the relative path is appended to, so include the trailing slash: "web/v42/". Default: none. */
@@ -23,7 +23,7 @@ export type LambderS3FileSourceOptions = {
  * An object's Content-Type is used unless it is a generic octet-stream, in
  * which case the extension decides, as for local files.
  */
-export declare class LambderS3FileSource implements LambderPublicFileSource {
+export declare class LambderS3FileSource implements LambderFileSource {
     private readonly bucket;
     private readonly prefix;
     private readonly clientConfig;
@@ -31,5 +31,5 @@ export declare class LambderS3FileSource implements LambderPublicFileSource {
     private sdk;
     constructor({ bucket, prefix, client, clientConfig }: LambderS3FileSourceOptions);
     private loadSdk;
-    read(relativePath: string): Promise<LambderPublicFile | null>;
+    read(relativePath: string): Promise<LambderFile | null>;
 }

package/package.json

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