lambder 2.0.18 → 3.1.1

package/dist/LambderPublicFiles.js

@@ -0,0 +1,108 @@
+import mimeTypeResolver from "mime-types";
+import { getFS, getPath } from "./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;
+/**
+ * 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,
+ * memory-cached, immutable-cache heuristic for content-hashed assets) and
+ * falls through to the route fallback when the file does not exist.
+ */
+export class LambderPublicFilesHandler {
+    publicPath;
+    options;
+    fileCache = new Map();
+    fileCacheBytes = 0;
+    constructor(publicPath, options) {
+        this.publicPath = publicPath;
+        this.options = options;
+    }
+    /** Serve the mapped file, or return null to fall through. */
+    async handle(ctx) {
+        const fs = await getFS();
+        const path = await getPath();
+        if (!fs || !path)
+            throw new Error("servePublicFiles requires a Node.js environment.");
+        const mappedPath = this.options.path ? this.options.path(ctx) : ctx.path;
+        if (!mappedPath)
+            return null;
+        const publicRoot = path.resolve(this.publicPath);
+        const filePath = this.resolveSafe(path, publicRoot, mappedPath);
+        if (!filePath)
+            return null;
+        const file = await this.readFileCached(fs, filePath);
+        if (!file)
+            return null;
+        const compressOption = this.options.compress;
+        const compress = typeof compressOption === "function" ? compressOption(ctx) : (compressOption ?? "auto");
+        return new LambderResponse({
+            statusCode: 200,
+            headers: {
+                "Content-Type": file.mimeType,
+                "Cache-Control": this.cacheControlFor(ctx, filePath),
+            },
+            body: file.body,
+            compress,
+        });
+    }
+    /** Join base+target and require the result to stay under base. */
+    resolveSafe(path, base, target) {
+        if (target.split("/").some((segment) => segment === ".."))
+            return null;
+        const normalizedTarget = target.startsWith("/") ? target.slice(1) : target;
+        const absolute = path.resolve(base, normalizedTarget);
+        if (absolute !== base && !absolute.startsWith(base + path.sep))
+            return null;
+        return absolute;
+    }
+    /** Read a file, caching small files in memory for warm invocations. */
+    async readFileCached(fs, filePath) {
+        const cached = this.fileCache.get(filePath);
+        if (cached)
+            return cached;
+        const stat = await fs.promises.stat(filePath).catch(() => null);
+        if (!stat?.isFile())
+            return null;
+        const body = await fs.promises.readFile(filePath);
+        const mimeType = mimeTypeResolver.lookup(filePath) || "application/octet-stream";
+        const entry = { body, mimeType };
+        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 (body.length <= maxFileBytes) {
+                // Evict oldest entries until the new file fits the budget.
+                for (const [key, value] of this.fileCache) {
+                    if (this.fileCacheBytes + body.length <= maxBytes)
+                        break;
+                    this.fileCache.delete(key);
+                    this.fileCacheBytes -= value.body.length;
+                }
+                if (this.fileCacheBytes + body.length <= maxBytes) {
+                    this.fileCache.set(filePath, entry);
+                    this.fileCacheBytes += body.length;
+                }
+            }
+        }
+        return entry;
+    }
+    cacheControlFor(ctx, filePath) {
+        const cacheOption = this.options.cacheControl;
+        if (typeof cacheOption === "function")
+            return cacheOption(ctx, filePath);
+        const immutablePattern = this.options.immutablePattern === false
+            ? null
+            : (this.options.immutablePattern ?? DEFAULT_IMMUTABLE_PATTERN);
+        if (immutablePattern && immutablePattern.test(filePath)) {
+            return this.options.immutableCacheControl ?? DEFAULT_IMMUTABLE_CACHE_CONTROL;
+        }
+        return cacheOption ?? DEFAULT_CACHE_CONTROL;
+    }
+}

package/dist/LambderResolver.d.ts

@@ -1,36 +1,35 @@
-import type { LambderRenderContext } from "./LambderContext.js";
-import LambderResponseBuilder, { LambderResolverResponse } from "./LambderResponseBuilder.js";
-import LambderUtils from "./LambderUtils.js";
-type MethodType<T, M extends keyof T> = T[M] extends (...args: any[]) => any ? T[M] : never;
-interface DieResolverMethods<TOutput> {
-    raw: MethodType<LambderResponseBuilder, 'raw'>;
-    json: MethodType<LambderResponseBuilder, 'json'>;
-    xml: MethodType<LambderResponseBuilder, 'xml'>;
-    html: MethodType<LambderResponseBuilder, 'html'>;
-    redirect: MethodType<LambderResponseBuilder, 'redirect'>;
-    status404: MethodType<LambderResponseBuilder, 'status404'>;
-    cors: MethodType<LambderResponseBuilder, 'cors'>;
-    fileBase64: MethodType<LambderResponseBuilder, 'fileBase64'>;
-    file: MethodType<LambderResponseBuilder, 'file'>;
-    ejsFile: MethodType<LambderResponseBuilder, 'ejsFile'>;
-    ejsTemplate: MethodType<LambderResponseBuilder, 'ejsTemplate'>;
-    api: (payload: TOutput | null, config?: Parameters<LambderResponseBuilder['api']>[1], headers?: Parameters<LambderResponseBuilder['api']>[2]) => LambderResolverResponse;
+import LambderResponseBuilder, { type LambderApiResponseConfig, type LambderResponseOptions } from "./LambderResponseBuilder.js";
+import type { LambderResponse } from "./LambderResponse.js";
+type SyncDie<T extends (...args: any[]) => LambderResponse> = (...args: Parameters<T>) => never;
+type AsyncDie<T extends (...args: any[]) => Promise<LambderResponse>> = (...args: Parameters<T>) => Promise<never>;
+export interface DieResolverMethods<TOutput> {
+    raw: SyncDie<LambderResponseBuilder["raw"]>;
+    json: SyncDie<LambderResponseBuilder["json"]>;
+    text: SyncDie<LambderResponseBuilder["text"]>;
+    xml: SyncDie<LambderResponseBuilder["xml"]>;
+    html: SyncDie<LambderResponseBuilder["html"]>;
+    status: SyncDie<LambderResponseBuilder["status"]>;
+    status404: SyncDie<LambderResponseBuilder["status404"]>;
+    redirect: SyncDie<LambderResponseBuilder["redirect"]>;
+    versionExpired: SyncDie<LambderResponseBuilder["versionExpired"]>;
+    fileBase64: SyncDie<LambderResponseBuilder["fileBase64"]>;
+    api: (payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions) => never;
+    apiBinary: (payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions) => never;
+    file: AsyncDie<LambderResponseBuilder["file"]>;
+    templateFile: AsyncDie<LambderResponseBuilder["templateFile"]>;
 }
+/**
+ * Response builder passed to route/api handlers and hooks.
+ *
+ * `res.die.*` builds the response and THROWS it, immediately halting the
+ * request at any call depth (handlers, hooks, nested service functions).
+ * Lambder's render pipeline catches thrown LambderResponse instances and uses
+ * them as the response. Plain `throw res.html(...)` works the same way.
+ */
 export default class LambderResolver<TOutput = any> extends LambderResponseBuilder<TOutput> {
-    resolve: (response: LambderResolverResponse) => void;
-    reject: (err: Error) => void;
     die: DieResolverMethods<TOutput>;
-    constructor({ isCorsEnabled, publicPath, apiVersion, lambderUtils, ctx, resolve, reject }: {
-        isCorsEnabled: boolean;
-        publicPath: string;
-        apiVersion?: string | null;
-        lambderUtils: LambderUtils;
-        ctx: LambderRenderContext<any>;
-        resolve: (response: LambderResolverResponse) => void;
-        reject: (err: Error) => void;
-    });
-    api(payload: TOutput | null, config?: Parameters<LambderResponseBuilder['api']>[1], headers?: Parameters<LambderResponseBuilder['api']>[2]): LambderResolverResponse;
-    private autoResolve;
-    private autoResolvePromise;
+    constructor(...args: ConstructorParameters<typeof LambderResponseBuilder>);
+    api(payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    apiBinary(payload: TOutput | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
 }
 export {};

package/dist/LambderResolver.js

@@ -1,52 +1,38 @@
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
+/**
+ * Response builder passed to route/api handlers and hooks.
+ *
+ * `res.die.*` builds the response and THROWS it, immediately halting the
+ * request at any call depth (handlers, hooks, nested service functions).
+ * Lambder's render pipeline catches thrown LambderResponse instances and uses
+ * them as the response. Plain `throw res.html(...)` works the same way.
+ */
 export default class LambderResolver extends LambderResponseBuilder {
-    resolve;
-    reject;
     die;
-    constructor({ isCorsEnabled, publicPath, apiVersion, lambderUtils, ctx, resolve, reject }) {
-        super({ isCorsEnabled, publicPath, apiVersion, lambderUtils, ctx, });
-        this.resolve = resolve;
-        this.reject = reject;
+    constructor(...args) {
+        super(...args);
         this.die = {
-            raw: this.autoResolve(this.raw),
-            json: this.autoResolve(this.json),
-            xml: this.autoResolve(this.xml),
-            html: this.autoResolve(this.html),
-            redirect: this.autoResolve(this.redirect),
-            status404: this.autoResolve(this.status404),
-            cors: this.autoResolve(this.cors),
-            fileBase64: this.autoResolve(this.fileBase64),
-            file: this.autoResolvePromise(this.file),
-            ejsFile: this.autoResolvePromise(this.ejsFile),
-            ejsTemplate: this.autoResolvePromise(this.ejsTemplate),
-            api: this.autoResolve(this.api),
+            raw: (...a) => { throw this.raw(...a); },
+            json: (...a) => { throw this.json(...a); },
+            text: (...a) => { throw this.text(...a); },
+            xml: (...a) => { throw this.xml(...a); },
+            html: (...a) => { throw this.html(...a); },
+            status: (...a) => { throw this.status(...a); },
+            status404: (...a) => { throw this.status404(...a); },
+            redirect: (...a) => { throw this.redirect(...a); },
+            versionExpired: (...a) => { throw this.versionExpired(...a); },
+            fileBase64: (...a) => { throw this.fileBase64(...a); },
+            api: (...a) => { throw this.api(...a); },
+            apiBinary: (...a) => { throw this.apiBinary(...a); },
+            file: async (...a) => { throw await this.file(...a); },
+            templateFile: async (...a) => { throw await this.templateFile(...a); },
         };
     }
-    // Override api method with proper typing
-    api(payload, config, headers) {
-        return super.api(payload, config, headers);
+    // Override api method with proper output typing
+    api(payload, config, options) {
+        return super.api(payload, config, options);
     }
-    autoResolve(method) {
-        return (...args) => {
-            const result = method.apply(this, args);
-            this.resolve(result);
-            return result;
-        };
-    }
-    autoResolvePromise(method) {
-        return (...args) => {
-            return new Promise((resolve, reject) => {
-                method.apply(this, args)
-                    .then(result => {
-                    this.resolve(result);
-                    resolve(result);
-                })
-                    .catch(err => {
-                    this.reject(err);
-                    reject(err);
-                });
-            });
-        };
+    apiBinary(payload, config, options) {
+        return super.apiBinary(payload, config, options);
     }
 }
-;

package/dist/LambderResponse.d.ts

@@ -0,0 +1,71 @@
+import type { LambderRenderContext } from "./LambderContext.js";
+export type HttpStatusCode = 100 | 101 | 200 | 201 | 202 | 203 | 204 | 206 | 300 | 301 | 302 | 303 | 304 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 408 | 409 | 410 | 412 | 413 | 415 | 416 | 418 | 422 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504;
+export type LambderHeadersInput = Record<string, string | string[]>;
+/**
+ * Final Lambda response: v1 (REST API) uses multiValueHeaders, v2 (HTTP API /
+ * Function URLs) uses headers + cookies. Assignable to both official aws-lambda
+ * result types (compile-time asserted below), so exporting getHandler() as an
+ * APIGatewayProxyHandler / APIGatewayProxyHandlerV2 is type-safe.
+ */
+export type LambderHttpResponse = {
+    statusCode: number;
+    body: string;
+    isBase64Encoded: boolean;
+    /** API Gateway REST API (payload v1). */
+    multiValueHeaders?: Record<string, string[]>;
+    /** API Gateway HTTP API / Lambda Function URLs (payload v2). */
+    headers?: Record<string, string>;
+    cookies?: string[];
+};
+export type LambderHttpEventFormat = "v1" | "v2";
+export declare const normalizeHeaders: (headers?: LambderHeadersInput) => Record<string, string[]>;
+export type LambderResponseInit = {
+    statusCode: HttpStatusCode;
+    headers?: LambderHeadersInput;
+    body?: string | Buffer | null;
+    /** True when body is already a base64-encoded string (pre-encoded binary content). */
+    isBodyBase64?: boolean;
+    /** "auto": gzip when enabled + compressible + large enough. true: force (if client accepts). false: never. */
+    compress?: boolean | "auto";
+    /** "auto": ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
+    etag?: boolean | "auto";
+};
+/**
+ * Intermediate response object returned by all response builder methods and by
+ * route/api handlers. Bodies stay uncompressed and un-encoded so hooks can
+ * still transform them; a single finalize step at the end of render() applies
+ * compression, ETag/304 handling and base64 encoding.
+ *
+ * Throwing a LambderResponse anywhere inside a handler or hook short-circuits
+ * the request: the thrown response becomes the response.
+ */
+export declare class LambderResponse {
+    statusCode: HttpStatusCode;
+    headers: Record<string, string[]>;
+    body: string | Buffer | null;
+    isBodyBase64: boolean;
+    compress: boolean | "auto";
+    etag: boolean | "auto";
+    constructor(init: LambderResponseInit);
+    getHeader(key: string): string[] | undefined;
+    setHeader(key: string, value: string | string[]): this;
+    addHeader(key: string, value: string): this;
+}
+export declare const isCompressibleContentType: (contentType: string | undefined) => boolean;
+export declare const acceptsEncoding: (acceptEncoding: string | undefined | null, encoding: string) => boolean;
+export type LambderFinalizeOptions = {
+    compression: false | {
+        minBytes: number;
+    };
+    etag: boolean;
+    /** Guard against Lambda's ~6MB response cap with a clear error. */
+    maxResponseBytes: number;
+};
+export declare const DEFAULT_FINALIZE_OPTIONS: LambderFinalizeOptions;
+/**
+ * Convert an intermediate LambderResponse into the final Lambda response:
+ * gzip negotiation (Accept-Encoding), ETag + If-None-Match 304, base64
+ * encoding, HEAD body stripping, and Lambda payload size guard. Emits the v1
+ * (REST API) or v2 (HTTP API / Function URL) response shape.
+ */
+export declare const finalizeResponse: (ctx: Pick<LambderRenderContext, "method" | "headers"> | null, response: LambderResponse, options: LambderFinalizeOptions, format?: LambderHttpEventFormat) => Promise<LambderHttpResponse>;

package/dist/LambderResponse.js

@@ -0,0 +1,196 @@
+import { getZlib, getCrypto } from "./node-polyfills.js";
+export const normalizeHeaders = (headers) => Object.fromEntries(Object.entries(headers ?? {}).map(([k, v]) => [k, Array.isArray(v) ? [...v] : [v]]));
+/**
+ * Intermediate response object returned by all response builder methods and by
+ * route/api handlers. Bodies stay uncompressed and un-encoded so hooks can
+ * still transform them; a single finalize step at the end of render() applies
+ * compression, ETag/304 handling and base64 encoding.
+ *
+ * Throwing a LambderResponse anywhere inside a handler or hook short-circuits
+ * the request: the thrown response becomes the response.
+ */
+export class LambderResponse {
+    statusCode;
+    headers;
+    body;
+    isBodyBase64;
+    compress;
+    etag;
+    constructor(init) {
+        this.statusCode = init.statusCode;
+        this.headers = normalizeHeaders(init.headers);
+        this.body = init.body ?? null;
+        this.isBodyBase64 = init.isBodyBase64 ?? false;
+        this.compress = init.compress ?? "auto";
+        this.etag = init.etag ?? "auto";
+    }
+    getHeader(key) {
+        const lower = key.toLowerCase();
+        for (const [k, v] of Object.entries(this.headers)) {
+            if (k.toLowerCase() === lower)
+                return v;
+        }
+        return undefined;
+    }
+    setHeader(key, value) {
+        const lower = key.toLowerCase();
+        for (const k of Object.keys(this.headers)) {
+            if (k.toLowerCase() === lower)
+                delete this.headers[k];
+        }
+        this.headers[key] = Array.isArray(value) ? [...value] : [value];
+        return this;
+    }
+    addHeader(key, value) {
+        const lower = key.toLowerCase();
+        const existingKey = Object.keys(this.headers).find((k) => k.toLowerCase() === lower);
+        if (existingKey) {
+            this.headers[existingKey].push(value);
+        }
+        else {
+            this.headers[key] = [value];
+        }
+        return this;
+    }
+}
+export const isCompressibleContentType = (contentType) => {
+    if (!contentType)
+        return false;
+    const mime = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+    if (mime.startsWith("text/"))
+        return true;
+    if (mime.endsWith("+json") || mime.endsWith("+xml"))
+        return true;
+    return [
+        "application/json",
+        "application/javascript",
+        "application/x-javascript",
+        "application/xml",
+        "application/wasm",
+        "image/svg+xml",
+        "application/lambder-json-stream",
+    ].includes(mime);
+};
+export const acceptsEncoding = (acceptEncoding, encoding) => {
+    if (!acceptEncoding)
+        return false;
+    return acceptEncoding.split(",").some((part) => {
+        const [token, ...params] = part.trim().split(";");
+        const name = (token ?? "").trim().toLowerCase();
+        if (name !== encoding && name !== "*")
+            return false;
+        const q = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+        return !q || Number(q.slice(2)) > 0;
+    });
+};
+export const DEFAULT_FINALIZE_OPTIONS = {
+    compression: { minBytes: 860 },
+    etag: true,
+    maxResponseBytes: 5_500_000,
+};
+const getRequestHeader = (ctx, name) => {
+    if (!ctx?.headers)
+        return undefined;
+    const lower = name.toLowerCase();
+    for (const [k, v] of Object.entries(ctx.headers)) {
+        if (k.toLowerCase() === lower)
+            return v ?? undefined;
+    }
+    return undefined;
+};
+/** Emit the format-specific Lambda response shape. */
+const emitResponse = (format, statusCode, headers, body, isBase64Encoded) => {
+    if (format === "v2") {
+        // Payload v2 has no multiValueHeaders: multi-values are comma-joined,
+        // except Set-Cookie which uses the dedicated cookies array.
+        const singleHeaders = {};
+        const cookies = [];
+        for (const [key, values] of Object.entries(headers)) {
+            if (key.toLowerCase() === "set-cookie")
+                cookies.push(...values);
+            else
+                singleHeaders[key] = values.join(", ");
+        }
+        return { statusCode, headers: singleHeaders, cookies, body, isBase64Encoded };
+    }
+    return { statusCode, multiValueHeaders: headers, body, isBase64Encoded };
+};
+/**
+ * Convert an intermediate LambderResponse into the final Lambda response:
+ * gzip negotiation (Accept-Encoding), ETag + If-None-Match 304, base64
+ * encoding, HEAD body stripping, and Lambda payload size guard. Emits the v1
+ * (REST API) or v2 (HTTP API / Function URL) response shape.
+ */
+export const finalizeResponse = async (ctx, response, options, format = "v1") => {
+    const method = (ctx?.method ?? "GET").toUpperCase();
+    if (response.body === null) {
+        return emitResponse(format, response.statusCode, response.headers, "", false);
+    }
+    let outBody;
+    let isBase64 = false;
+    if (response.isBodyBase64) {
+        // Pre-encoded binary content: passes through untouched (no compression).
+        outBody = String(response.body);
+        isBase64 = true;
+    }
+    else {
+        let bodyBuffer = Buffer.isBuffer(response.body)
+            ? response.body
+            : Buffer.from(String(response.body), "utf8");
+        const contentType = response.getHeader("Content-Type")?.[0];
+        const alreadyEncoded = !!response.getHeader("Content-Encoding");
+        const eligibleForCompression = !alreadyEncoded && (response.compress === true ||
+            (response.compress === "auto" &&
+                options.compression !== false &&
+                bodyBuffer.length >= options.compression.minBytes &&
+                isCompressibleContentType(contentType)));
+        if (eligibleForCompression) {
+            // Vary even when this client didn't accept an encoding, to keep caches correct.
+            response.addHeader("Vary", "Accept-Encoding");
+            if (acceptsEncoding(getRequestHeader(ctx, "accept-encoding"), "gzip")) {
+                const zlib = await getZlib();
+                if (zlib) {
+                    bodyBuffer = zlib.gzipSync(bodyBuffer);
+                    response.setHeader("Content-Encoding", "gzip");
+                }
+            }
+        }
+        if (Buffer.isBuffer(response.body) || response.getHeader("Content-Encoding")) {
+            outBody = bodyBuffer.toString("base64");
+            isBase64 = true;
+        }
+        else {
+            outBody = bodyBuffer.toString("utf8");
+        }
+    }
+    const etagEnabled = response.etag === true || (response.etag === "auto" &&
+        options.etag &&
+        response.statusCode === 200 &&
+        (method === "GET" || method === "HEAD"));
+    if (etagEnabled) {
+        const crypto = await getCrypto();
+        if (crypto) {
+            const etagValue = `"${crypto.createHash("sha256").update(outBody).digest("hex").slice(0, 32)}"`;
+            response.setHeader("ETag", etagValue);
+            const ifNoneMatch = getRequestHeader(ctx, "if-none-match");
+            if (ifNoneMatch && ifNoneMatch.split(",").map((s) => s.trim()).includes(etagValue)) {
+                const preservedHeaders = {};
+                for (const key of ["ETag", "Cache-Control", "Vary", "Expires", "Last-Modified"]) {
+                    const value = response.getHeader(key);
+                    if (value)
+                        preservedHeaders[key] = value;
+                }
+                return emitResponse(format, 304, preservedHeaders, "", false);
+            }
+        }
+    }
+    if (method === "HEAD") {
+        return emitResponse(format, response.statusCode, response.headers, "", false);
+    }
+    if (outBody.length > options.maxResponseBytes) {
+        throw new Error(`Lambder: final response body is ${outBody.length} bytes which exceeds the configured ` +
+            `maxResponseBytes (${options.maxResponseBytes}). Lambda caps proxy responses at ~6MB. ` +
+            `Consider pagination or enabling compression.`);
+    }
+    return emitResponse(format, response.statusCode, response.headers, outBody, isBase64);
+};

package/dist/LambderResponseBuilder.d.ts

@@ -1,11 +1,16 @@
-import LambderUtils from "./LambderUtils.js";
-import { LambderRenderContext } from "./LambderContext.js";
-export type HttpStatusCode = 200 | 201 | 202 | 204 | 300 | 301 | 302 | 303 | 304 | 307 | 308 | 400 | 401 | 403 | 404 | 405 | 409 | 410 | 413 | 415 | 422 | 429 | 500 | 501 | 502 | 503 | 504;
-export type LambderResolverResponse = {
-    statusCode: HttpStatusCode;
-    multiValueHeaders?: Record<string, string[]>;
-    body: string | null;
-    isBase64Encoded?: boolean;
+import type { LambderRenderContext } from "./LambderContext.js";
+import { LambderResponse, type HttpStatusCode, type LambderHeadersInput } from "./LambderResponse.js";
+import { LambderSafeHtml } from "./LambderHtml.js";
+import { type LambderTemplateData } from "./LambderTemplatingEngine.js";
+export type LambderResponseOptions = {
+    statusCode?: HttpStatusCode;
+    headers?: LambderHeadersInput;
+    /** Shorthand for the Cache-Control header. */
+    cacheControl?: string;
+    /** "auto" (default): gzip when compressible/large enough. true: force. false: never. */
+    compress?: boolean | "auto";
+    /** "auto" (default): ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
+    etag?: boolean | "auto";
 };
 export type LambderApiResponseConfig = {
     versionExpired?: boolean;
@@ -16,38 +21,58 @@ export type LambderApiResponseConfig = {
     logList?: any[];
 };
 export type LambderApiResponse<T> = LambderApiResponseConfig & {
+    apiVersion?: string | null;
     payload?: T | null;
 };
+export type LambderRawResponseInit = {
+    statusCode: HttpStatusCode;
+    headers?: LambderHeadersInput;
+    /** Legacy alias for headers (API Gateway naming). */
+    multiValueHeaders?: Record<string, string[]>;
+    body: string | Buffer | null;
+    /** True when body is already a base64-encoded string. */
+    isBase64Encoded?: boolean;
+    compress?: boolean | "auto";
+    etag?: boolean | "auto";
+};
 export default class LambderResponseBuilder<TResponse = any> {
-    private isCorsEnabled;
-    private publicPath;
-    private apiVersion;
-    private lambderUtils;
-    private ctx?;
-    constructor({ isCorsEnabled, publicPath, apiVersion, lambderUtils, ctx }: {
-        isCorsEnabled: boolean;
+    protected publicPath: string;
+    protected apiVersion: string | null;
+    protected ctx?: LambderRenderContext;
+    constructor({ publicPath, apiVersion, ctx }: {
         publicPath: string;
         apiVersion?: string | null;
-        lambderUtils: LambderUtils;
-        ctx?: LambderRenderContext<any>;
+        ctx?: LambderRenderContext;
     });
-    private readPublicFileSync;
-    private checkPublicFileExist;
+    private buildResponse;
+    private resolvePublicFilePath;
     addHeader(key: string, value: string): void;
     setHeader(key: string, value: string | string[]): void;
     logToApiResponse(input: any): void;
-    raw(param: LambderResolverResponse): LambderResolverResponse;
-    json(data: Record<string, any>, headers?: Record<string, string | string[]>): LambderResolverResponse;
-    xml(data: string): LambderResolverResponse;
-    html(data: string, headers?: Record<string, string | string[]>): LambderResolverResponse;
-    redirect(url: string, statusCode?: HttpStatusCode, headers?: Record<string, string | string[]>): LambderResolverResponse;
-    status404(data: string, headers?: Record<string, string | string[]>): LambderResolverResponse;
-    versionExpired(headers?: Record<string, string | string[]>): LambderResolverResponse;
-    cors(): LambderResolverResponse;
-    fileBase64(fileBase64: string, mimeType: string, headers?: Record<string, string | string[]>): LambderResolverResponse;
-    file(filePath: string, headers?: Record<string, string | string[]>, fallbackFilePath?: string): Promise<LambderResolverResponse>;
-    ejsTemplate(template: string, pageData: Record<string, any>, headers?: Record<string, string | string[]>): Promise<LambderResolverResponse>;
-    ejsFile(filePath: string, pageData: Record<string, any>, headers?: Record<string, string | string[]>): Promise<LambderResolverResponse>;
-    api(payload: TResponse | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, }?: LambderApiResponseConfig, headers?: Record<string, string | string[]>): LambderResolverResponse;
-    apiBinary<T = any>(payload: T | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, }?: LambderApiResponseConfig, headers?: Record<string, string | string[]>): LambderResolverResponse;
+    raw(init: LambderRawResponseInit): LambderResponse;
+    json(data: Record<string, any>, options?: LambderResponseOptions): LambderResponse;
+    text(data: string, options?: LambderResponseOptions): LambderResponse;
+    xml(data: string | LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
+    html(data: string | LambderSafeHtml, options?: LambderResponseOptions): LambderResponse;
+    status(statusCode: HttpStatusCode, body?: string, options?: LambderResponseOptions): LambderResponse;
+    status404(data: string, options?: LambderResponseOptions): LambderResponse;
+    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>;
+    /**
+     * 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.
+     */
+    templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
+        htmlVirtualSlots?: boolean;
+    }): Promise<LambderResponse>;
+    api(payload: TResponse | null, { versionExpired, sessionExpired, notAuthorized, message, errorMessage, logList, }?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
+    /** Same as api() but forces gzip compression of the response body. */
+    apiBinary(payload: TResponse | null, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
 }