lambder 8.3.1 → 9.0.1

package/dist/core/LambderContext.d.ts

@@ -2,6 +2,7 @@ import type { APIGatewayProxyEvent, APIGatewayProxyEventV2, APIGatewayProxyEvent
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import { type LambderApiRequest } from "../api/LambderApiRequest.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
+import { type LambderResponseTools } from "../api/LambderApiCallContext.js";
 import type LambderSessionController from "../session/LambderSessionController.js";
 import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult } from "../api/LambderApiRateLimits.js";
 export type LambderHttpEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
@@ -19,7 +20,9 @@ export declare const isV2HttpEvent: (event: unknown) => event is APIGatewayProxy
  * API core's call context (session, guardData, responseHeaders, logList),
  * which is the part the pipeline and the session controller work on; the
  * rest is the HTTP request as the Lambda event delivered it, plus the tools
- * the instance rendering it binds on (sessionController, rateLimit, isRateLimited).
+ * the instance rendering it binds on (sessionController, rateLimit, isRateLimited)
+ * and the response tools (setResponseHeader, addResponseHeader, setCookie,
+ * clearCookie) that write onto whatever answer the request ends with.
  *
  * TRateLimitPolicies is the app's policies map on a handler registered with
  * addApi, addSessionApi, addRoute or addSessionRoute, so a policy name is
@@ -102,9 +105,9 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     lambdaContext: Context;
     /** Which API Gateway payload format the event arrived in, and the response leaves in. */
     eventFormat: LambderHttpEventFormat;
-    /** Response headers written during the request (res.setHeader, res.addHeader, session cookies), applied onto the response at the end. */
+    /** Response headers written during the request (the response tools below, session cookies), applied onto the response at the end. */
     responseHeaders: LambderAnswerHeaders;
-    /** Entries for the API envelope's logList channel (res.logToApiResponse). */
+    /** Entries for the API envelope's logList channel: a handler pushes what it wants the caller's debug log to show. */
     logList: unknown[];
     /**
      * Sessions for this request: read the one it carries
@@ -125,12 +128,12 @@ export type LambderRenderContext<TApiPayload = any, TPathParams extends Record<s
     rateLimit: LambderContextRateLimit<TRateLimitPolicies>;
     /** The same count as rateLimit, answered instead of thrown: false, or the window that refused and its retryAfterSeconds. */
     isRateLimited: LambderContextRateLimitCheck<TRateLimitPolicies>;
-};
+} & LambderResponseTools;
 export type LambderSessionRenderContext<TApiPayload = any, SessionData = any, TPathParams extends Record<string, string> = Record<string, string>, TGuardData = {}, TRateLimitPolicies = Record<string, LambderApiRateLimitPolicyConfig>> = Omit<LambderRenderContext<TApiPayload, TPathParams, TGuardData, SessionData, TRateLimitPolicies>, 'session'> & {
     session: LambderSessionRecord<SessionData>;
 };
-/** The members of a render context that belong to the instance rendering the request rather than to its event. */
-type LambderContextToolName = "sessionController" | "rateLimit" | "isRateLimited";
+/** The members of a render context that are bound onto it rather than read from its event. */
+type LambderContextToolName = "sessionController" | "rateLimit" | "isRateLimited" | keyof LambderResponseTools;
 /** What an instance binds onto each context it renders: see bindContextTools. */
 export type LambderContextTools = {
     sessionControllerFor: (ctx: LambderRenderContext) => LambderSessionController<any>;

package/dist/core/LambderContext.js

@@ -4,7 +4,7 @@ import { base64ToText } from "../shared/util/LambderBase64.js";
 import { LambderAnswerHeaders } from "../shared/wire/LambderAnswerHeaders.js";
 import { DEFAULT_API_PATH } from "../shared/wire/LambderDefaultApiPath.js";
 import { LAMBDER_INVOKE_API_ID, LAMBDER_LOCAL_API_ID } from "../shared/wire/LambderInvokeApiId.js";
-import { bindCallTools } from "../api/LambderApiCallContext.js";
+import { bindCallTools, responseToolsOf } from "../api/LambderApiCallContext.js";
 import { decodeRequestPath } from "./LambderRequestPath.js";
 /** True for API Gateway HTTP API / Lambda Function URL (payload v2) events. */
 export const isV2HttpEvent = (event) => !!event && typeof event === "object"
@@ -23,6 +23,7 @@ export const bindContextTools = (ctx, tools) => {
         methods: {
             rateLimit: async (policy, key) => { await tools.chargeRateLimit(bound, policy, key, true); },
             isRateLimited: (policy, key) => tools.chargeRateLimit(bound, policy, key, false),
+            ...responseToolsOf(bound, bound.host),
         },
     });
     return bound;

package/dist/core/LambderResolver.d.ts

@@ -1,10 +1,9 @@
-import type { LambderApiNullAnswerConfig } from "../shared/wire/LambderApiContract.js";
-import LambderResponseBuilder, { type LambderResolverApiMethod, type LambderApiResponseConfig, type LambderResponseOptions } from "./LambderResponseBuilder.js";
+import LambderResponseBuilder 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>;
 /** The `res.die.*` surface: every builder method, throwing what it built. Internal to the resolver, which is the only thing that has one. */
-interface DieResolverMethods<TOutput> {
+interface DieResolverMethods {
     raw: SyncDie<LambderResponseBuilder["raw"]>;
     json: SyncDie<LambderResponseBuilder["json"]>;
     text: SyncDie<LambderResponseBuilder["text"]>;
@@ -15,25 +14,20 @@ interface DieResolverMethods<TOutput> {
     redirect: SyncDie<LambderResponseBuilder["redirect"]>;
     versionExpired: SyncDie<LambderResponseBuilder["versionExpired"]>;
     fileBase64: SyncDie<LambderResponseBuilder["fileBase64"]>;
-    api: LambderResolverApiMethod<TOutput, never>;
-    apiBinary: LambderResolverApiMethod<TOutput, never>;
+    api: SyncDie<LambderResponseBuilder["api"]>;
     file: AsyncDie<LambderResponseBuilder["file"]>;
     templateFile: AsyncDie<LambderResponseBuilder["templateFile"]>;
 }
 /**
- * Response builder passed to route/api handlers and hooks.
+ * Response builder passed to route 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> {
-    die: DieResolverMethods<TOutput>;
+export default class LambderResolver extends LambderResponseBuilder {
+    die: DieResolverMethods;
     constructor(...args: ConstructorParameters<typeof LambderResponseBuilder>);
-    api(payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    api(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
 }
 export {};

package/dist/core/LambderResolver.js

@@ -1,6 +1,6 @@
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
 /**
- * Response builder passed to route/api handlers and hooks.
+ * Response builder passed to route handlers and hooks.
  *
  * `res.die.*` builds the response and THROWS it, immediately halting the
  * request at any call depth (handlers, hooks, nested service functions).
@@ -22,21 +22,9 @@ export default class LambderResolver extends LambderResponseBuilder {
             redirect: (...a) => { throw this.redirect(...a); },
             versionExpired: (...a) => { throw this.versionExpired(...a); },
             fileBase64: (...a) => { throw this.fileBase64(...a); },
-            // Overloaded on the payload (see LambderApiAnswer); the implementation takes both shapes.
-            api: ((payload, config, options) => {
-                throw this.api(payload, config, options);
-            }),
-            apiBinary: ((payload, config, options) => {
-                throw this.apiBinary(payload, config, options);
-            }),
+            api: (...a) => { throw this.api(...a); },
             file: async (...a) => { throw await this.file(...a); },
             templateFile: async (...a) => { throw await this.templateFile(...a); },
         };
     }
-    api(payload, config, options) {
-        return super.api(payload, config, options);
-    }
-    apiBinary(payload, config, options) {
-        return super.apiBinary(payload, config, options);
-    }
 }

package/dist/core/LambderResponseBuilder.d.ts

@@ -1,12 +1,10 @@
-import type { z } from "zod";
 import type { LambderRenderContext } from "./LambderContext.js";
-import { type LambderCookieOptions, type LambderClearCookieOptions } from "../shared/wire/LambderCookie.js";
 import type { LambderFiles } from "./LambderFiles.js";
 import { LambderResponse, type LambderHeadersInput } from "./LambderResponse.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import { LambderSafeHtml } from "../shared/LambderHtml.js";
 import type { LambderTemplateData } from "./LambderTemplatingEngine.js";
-import type { LambderApiResponseConfig, LambderApiNullAnswerConfig } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 export type { LambderApiEnvelopeBody, LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 export type LambderResponseOptions = {
     statusCode?: LambderHttpStatusCode;
@@ -18,19 +16,6 @@ export type LambderResponseOptions = {
     /** "auto" (default): ETag on GET/HEAD 200 when globally enabled. true: force. false: never. */
     etag?: boolean | "auto";
 };
-/**
- * The two shapes of an API answer: the output the contract declares, or
- * `null` beside a config that says why (a refusal flag, an `errorMessage`, a
- * `message`). A bare `res.api(null)` compiles only when the output type
- * itself allows null, so a success payload is always the declared output,
- * which lets a typed caller (LambderInvokeCaller.api) promise it. Untyped
- * resolvers (`TOutput = any`) accept anything. This is the resolver's method
- * type; the core's answer type is LambderApiAnswer.
- */
-export type LambderResolverApiMethod<TOutput, TResult> = {
-    (payload: TOutput, config?: LambderApiResponseConfig, options?: LambderResponseOptions): TResult;
-    (payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): TResult;
-};
 export type LambderRawResponseInit = {
     statusCode: LambderHttpStatusCode;
     headers?: LambderHeadersInput;
@@ -40,39 +25,23 @@ export type LambderRawResponseInit = {
     compress?: boolean | "auto";
     etag?: boolean | "auto";
 };
-export default class LambderResponseBuilder<TResponse = any> {
+/**
+ * Builds the responses of routes, hooks and error handlers. An API handler
+ * never holds one: it returns its output or refuses, and writes headers and
+ * cookies through its context (LambderResponseTools).
+ */
+export default class LambderResponseBuilder {
     protected files: LambderFiles | null;
     protected apiVersion: string | null;
     protected ctx?: LambderRenderContext;
-    /** The output schema of the API this builder answers, which every success payload is parsed through; null outside an API handler. */
-    protected apiOutput: z.ZodType | null;
-    constructor({ files, apiVersion, ctx, apiOutput }: {
+    constructor({ files, apiVersion, ctx }: {
         files?: LambderFiles | null;
         apiVersion?: string | null;
         ctx?: LambderRenderContext;
-        apiOutput?: z.ZodType;
     });
     private buildResponse;
     /** The instance's file reader, which res.file and res.templateFile need. */
     private requireFiles;
-    /** Appends a response header; applied onto the response once the handler has one, in call order. */
-    addHeader(key: string, value: string): void;
-    /** Replaces a response header; applied onto the response once the handler has one, in call order. */
-    setHeader(key: string, value: string | string[]): void;
-    /**
-     * Adds a Set-Cookie header. A function-form `domain` is resolved against
-     * the request hostname. Defaults: Path=/, SameSite=Lax, Secure, not
-     * HttpOnly, browser-session lifetime.
-     */
-    setCookie(name: string, value: string, options?: LambderCookieOptions): void;
-    /**
-     * Adds a Set-Cookie header that deletes the cookie. Pass the same
-     * `domain` and `path` the cookie was set with: a cookie's identity is
-     * (name, domain, path), and a deletion under a different scope targets a
-     * different cookie and deletes nothing.
-     */
-    clearCookie(name: string, options?: LambderClearCookieOptions): void;
-    logToApiResponse(input: unknown): void;
     raw(init: LambderRawResponseInit): LambderResponse;
     json(data: Record<string, any>, options?: LambderResponseOptions): LambderResponse;
     text(data: string, options?: LambderResponseOptions): LambderResponse;
@@ -109,37 +78,13 @@ export default class LambderResponseBuilder<TResponse = any> {
     templateFile(filePath: string, data?: LambderTemplateData, options?: LambderResponseOptions & {
         htmlVirtualSlots?: boolean;
     }): Promise<LambderResponse>;
-    api(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    api(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
     /**
-     * A payload as the API's output schema declares it. The type system
-     * accepts a value that carries more than the schema (a row read straight
-     * from a table is assignable to a narrower object type), and without this
-     * the extra fields, a password hash included, would reach the client.
-     * zod strips what the schema does not declare, fills its defaults and
-     * applies its transforms, so the wire and the idempotency store only see
-     * the declared shape. A refusal's payload beside an errorMessage or a
-     * flag is parsed the same way; only null passes as it is. Only an API
-     * handler's own resolver holds the schema: a hook, a validation handler
-     * or an error handler answers in shapes of its own, a cached answer in
-     * its wire form, and is sent as given.
-     *
-     * The payload is the schema's input form (what a handler writes before
-     * the transforms), so a transform runs exactly once. A payload the schema
-     * rejects is a handler breaking its contract, answered as a crash rather
-     * than sent (LambderApiOutputValidationError, which an idempotency key
-     * records as its answer, since the handler has already run).
-     *
-     * The parse is synchronous, so an output schema cannot be async: zod
-     * throws from a synchronous parse that meets an async refinement or
-     * transform, and a transform may throw of its own accord. Either throw
-     * becomes the same LambderApiOutputValidationError, carrying what was
-     * thrown as its cause. Left to escape as it is, it would read as the
-     * handler crashing before its answer: the idempotency engine would
-     * release the key's claim and every retry would run the operation again.
+     * An API envelope written by hand: what a hook, an input validation
+     * handler or a global error handler answers an API call with (a refusal
+     * flag, an errorMessage, a crash). The payload goes out as given; an API
+     * handler's own output is parsed through its schema by the instance
+     * instead. The logList channel is what the request accumulated unless the
+     * config names its own.
      */
-    private declaredPayload;
-    /** Same as api() but forces compression of the response body. */
-    apiBinary(payload: TResponse, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
-    apiBinary(payload: null, config: LambderApiNullAnswerConfig, options?: LambderResponseOptions): LambderResponse;
+    api(payload: unknown, config?: LambderApiResponseConfig, options?: LambderResponseOptions): LambderResponse;
 }

package/dist/core/LambderResponseBuilder.js

@@ -1,18 +1,18 @@
-import { serializeCookie, serializeClearCookie } from "../shared/wire/LambderCookie.js";
 import { LambderResponse } from "./LambderResponse.js";
 import { buildApiEnvelope } from "../api/LambderApiEnvelope.js";
-import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
+/**
+ * Builds the responses of routes, hooks and error handlers. An API handler
+ * never holds one: it returns its output or refuses, and writes headers and
+ * cookies through its context (LambderResponseTools).
+ */
 export default class LambderResponseBuilder {
     files;
     apiVersion;
     ctx;
-    /** The output schema of the API this builder answers, which every success payload is parsed through; null outside an API handler. */
-    apiOutput;
-    constructor({ files, apiVersion, ctx, apiOutput }) {
+    constructor({ files, apiVersion, ctx }) {
         this.files = files ?? null;
         this.apiVersion = apiVersion ?? null;
         this.ctx = ctx;
-        this.apiOutput = apiOutput ?? null;
     }
     ;
     buildResponse(statusCode, contentType, body, options, defaults) {
@@ -37,49 +37,6 @@ export default class LambderResponseBuilder {
             throw new Error(`Lambder: ${method} requires the files option at creation (e.g. files: new LambderLocalFileSource({ root }))`);
         return this.files;
     }
-    /** Appends a response header; applied onto the response once the handler has one, in call order. */
-    addHeader(key, value) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.addHeader needs the request context, and this response builder was created without one.");
-        this.ctx.responseHeaders.add(key, value);
-    }
-    ;
-    /** Replaces a response header; applied onto the response once the handler has one, in call order. */
-    setHeader(key, value) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.setHeader needs the request context, and this response builder was created without one.");
-        this.ctx.responseHeaders.set(key, value);
-    }
-    ;
-    /**
-     * Adds a Set-Cookie header. A function-form `domain` is resolved against
-     * the request hostname. Defaults: Path=/, SameSite=Lax, Secure, not
-     * HttpOnly, browser-session lifetime.
-     */
-    setCookie(name, value, options) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.setCookie needs the request context, and this response builder was created without one.");
-        this.addHeader("Set-Cookie", serializeCookie(name, value, options, this.ctx.host));
-    }
-    ;
-    /**
-     * Adds a Set-Cookie header that deletes the cookie. Pass the same
-     * `domain` and `path` the cookie was set with: a cookie's identity is
-     * (name, domain, path), and a deletion under a different scope targets a
-     * different cookie and deletes nothing.
-     */
-    clearCookie(name, options) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.clearCookie needs the request context, and this response builder was created without one.");
-        this.addHeader("Set-Cookie", serializeClearCookie(name, options, this.ctx.host));
-    }
-    ;
-    logToApiResponse(input) {
-        if (!this.ctx)
-            throw new Error("Lambder: res.logToApiResponse needs the request context, and this response builder was created without one.");
-        this.ctx.logList.push(input);
-    }
-    ;
     raw(init) {
         return new LambderResponse({
             statusCode: init.statusCode,
@@ -177,58 +134,17 @@ export default class LambderResponseBuilder {
         return this.buildResponse(200, "text/html; charset=utf-8", template.render(data), options);
     }
     ;
-    api(payload, config = {}, options) {
-        // The envelope is the core's (one writer for both the server and the
-        // mock runtime); the logList channel is what this request accumulated
-        // unless the config names its own.
-        const envelope = buildApiEnvelope(this.apiVersion, this.declaredPayload(payload), { ...config, logList: config.logList || this.ctx?.logList });
-        return this.json(envelope, options);
-    }
-    ;
     /**
-     * A payload as the API's output schema declares it. The type system
-     * accepts a value that carries more than the schema (a row read straight
-     * from a table is assignable to a narrower object type), and without this
-     * the extra fields, a password hash included, would reach the client.
-     * zod strips what the schema does not declare, fills its defaults and
-     * applies its transforms, so the wire and the idempotency store only see
-     * the declared shape. A refusal's payload beside an errorMessage or a
-     * flag is parsed the same way; only null passes as it is. Only an API
-     * handler's own resolver holds the schema: a hook, a validation handler
-     * or an error handler answers in shapes of its own, a cached answer in
-     * its wire form, and is sent as given.
-     *
-     * The payload is the schema's input form (what a handler writes before
-     * the transforms), so a transform runs exactly once. A payload the schema
-     * rejects is a handler breaking its contract, answered as a crash rather
-     * than sent (LambderApiOutputValidationError, which an idempotency key
-     * records as its answer, since the handler has already run).
-     *
-     * The parse is synchronous, so an output schema cannot be async: zod
-     * throws from a synchronous parse that meets an async refinement or
-     * transform, and a transform may throw of its own accord. Either throw
-     * becomes the same LambderApiOutputValidationError, carrying what was
-     * thrown as its cause. Left to escape as it is, it would read as the
-     * handler crashing before its answer: the idempotency engine would
-     * release the key's claim and every retry would run the operation again.
+     * An API envelope written by hand: what a hook, an input validation
+     * handler or a global error handler answers an API call with (a refusal
+     * flag, an errorMessage, a crash). The payload goes out as given; an API
+     * handler's own output is parsed through its schema by the instance
+     * instead. The logList channel is what the request accumulated unless the
+     * config names its own.
      */
-    declaredPayload(payload) {
-        if (!this.apiOutput || payload === null)
-            return payload;
-        const apiName = this.ctx?.apiName ?? "?";
-        let parsed;
-        try {
-            parsed = this.apiOutput.safeParse(payload);
-        }
-        catch (thrown) {
-            throw new LambderApiOutputValidationError(apiName, { thrown });
-        }
-        if (parsed.success)
-            return parsed.data;
-        throw new LambderApiOutputValidationError(apiName, { zodError: parsed.error });
-    }
-    apiBinary(payload, config = {}, options) {
-        return this.api(payload, config, { ...options, compress: true });
+    api(payload, config = {}, options) {
+        const envelope = buildApiEnvelope(this.apiVersion, payload, { ...config, logList: config.logList || this.ctx?.logList });
+        return this.json(envelope, options);
     }
     ;
 }

package/dist/index.d.ts

@@ -30,7 +30,7 @@ export { toHttpAnswer } from "./api/LambderApiAnswer.js";
 export type { LambderApiAnswer } from "./api/LambderApiAnswer.js";
 export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader } from "./shared/wire/LambderAnswerHeaders.js";
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
-export type { LambderApiCallContext, LambderApiCallTrace } from "./api/LambderApiCallContext.js";
+export type { LambderApiCallContext, LambderApiCallTrace, LambderResponseTools } from "./api/LambderApiCallContext.js";
 export type { LambderApiDefinition } from "./api/LambderApiDefinition.js";
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
 export type { LambderApiSignatureEntry } from "./api/LambderApiSignature.js";
@@ -68,7 +68,7 @@ export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
-export type { LambderResponseOptions, LambderRawResponseInit, LambderResolverApiMethod, } from "./core/LambderResponseBuilder.js";
+export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
 export type { LambderRouteMatcher, LambderRouteConditionFn, LambderRouteCondition, LambderPathParamsOf, LambderRoutePath } from "./core/LambderRouting.js";
 export type { LambderCorsConfig } from "./core/LambderCors.js";
 export type { LambderCreateOptions, LambderSessionOptions, LambderActionTools, LambderHandler, } from "./core/LambderCreateOptions.js";
@@ -133,7 +133,7 @@ export { apiGuardParam } from "./shared/wire/LambderApiOptionEntries.js";
 export type { LambderApiOptionEntries, LambderApiOptionEntry, LambderRateLimitPolicyEntry, LambderGuardDeclarationEntry, LambderApisWithGuard, LambderApisGuardedBy, LambderApisWithMode, LambderGuardParamOf, } from "./shared/wire/LambderApiOptionEntries.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/index.js

@@ -99,5 +99,5 @@ export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
 export { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, 
 // The Brotli twin of the browser's compressPayloadGzip, and its defaults.
 DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, compressPayloadBrotli, } from "./shared/wire/LambderRequestPayload.js";
-// Cookies (res.setCookie / res.clearCookie build on these; exported for code holding a LambderResponse)
+// Cookies (ctx.setCookie / ctx.clearCookie build on these; exported for code holding a LambderResponse)
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./shared/wire/LambderCookie.js";

package/dist/invoke/LambderInvokeCaller.js

@@ -378,10 +378,9 @@ export default class LambderInvokeCaller {
         // The answer's Set-Cookie values, so a session the callee rotated or
         // cleared is visible to whoever is carrying it.
         const cookies = http.cookies;
-        // The declared output, by the callee's own typing: res.api(null)
-        // compiles only for an output that allows null or beside a reason (an
-        // errorMessage is a failure below; a message-only null is the
-        // callee's contract to keep).
+        // The declared output, by the callee's own typing: a handler returns
+        // its output, so a success payload is null only where the output
+        // allows null.
         if (outcome.ok)
             return { ok: true, payload: (outcome.payload ?? null), response: outcome.response, logList, cookies };
         const shared = { status: outcome.status, retryAfterSeconds: outcome.retryAfterSeconds, logList, cookies };

package/dist/mock/LambderMockApp.js

@@ -1,6 +1,6 @@
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
-import { bindCallTools, createApiCallContext } from "../api/LambderApiCallContext.js";
+import { bindCallTools, createApiCallContext, responseToolsOf } from "../api/LambderApiCallContext.js";
 import { toHttpAnswer } from "../api/LambderApiAnswer.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { buildApiEnvelope, envelopeAnswer, crashAnswer, } from "../api/LambderApiEnvelope.js";
@@ -562,7 +562,6 @@ export class LambderMockApp {
             apiName: request.apiName,
             request,
             signal: request.signal ?? new AbortController().signal,
-            envelope: {},
             payload: request.payload,
             guardInputs: request.guardInputs,
             // The key as a handler can use it. A non-string is not a key: the
@@ -591,6 +590,7 @@ export class LambderMockApp {
             methods: {
                 rateLimit: async (policy, key) => { await chargeRateLimit(policy, key, true); },
                 isRateLimited: (policy, key) => chargeRateLimit(policy, key, false),
+                ...responseToolsOf(ctx, request.host),
             },
         });
         return ctx;
@@ -683,7 +683,6 @@ export class LambderMockApp {
                         callCtx.payload = request.payload;
                         const payload = await handler(callCtx);
                         return envelopeAnswer(buildApiEnvelope(this.apiVersion, payload === undefined ? null : payload, {
-                            message: callCtx.envelope.message,
                             logList: callCtx.logList,
                         }));
                     }

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -282,8 +282,8 @@ export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicie
 };
 /**
  * What the server's input validation handler answers, as a mock states it:
- * `res.api(payload, config)` as data, with the status it went out with (200
- * unless named).
+ * the handler's `res.api(payload, config)` as data, with the status it went
+ * out with (200 unless named).
  */
 export type LambderMockInvalidInputAnswer = {
     payload?: unknown;

package/dist/mock/LambderMockTypes.d.ts

@@ -9,7 +9,7 @@ import type { z } from "zod";
 import type { LambderApiMode, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractGuardInputsOf, LambderContractGuardNames, LambderContractGuardsOf, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard, LambderGuardDataOf, LambderGuardMetaMap } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck } from "../api/LambderApiRateLimits.js";
-import type { LambderApiCallContext } from "../api/LambderApiCallContext.js";
+import type { LambderApiCallContext, LambderResponseTools } from "../api/LambderApiCallContext.js";
 import type { LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { LambderApiDefinition } from "../api/LambderApiDefinition.js";
@@ -47,7 +47,7 @@ export type LambderMockSurplusKeys<TOptions, TShape> = [
  * fields: the API core's call context plus the request, a session
  * controller for the call, and the caller's abort signal.
  */
-export type LambderMockCallContext<S = any> = LambderApiCallContext<S> & {
+export type LambderMockCallContext<S = any> = LambderApiCallContext<S> & LambderResponseTools & {
     apiName: string;
     request: LambderApiRequest;
     /** Create, rotate, refresh and end sessions, exactly as a server handler does through its own ctx.sessionController. */
@@ -61,15 +61,6 @@ export type LambderMockCallContext<S = any> = LambderApiCallContext<S> & {
     /** The same count, answered instead of thrown, as ctx.isRateLimited on the server. */
     isRateLimited: LambderContextRateLimitCheck<Record<string, LambderApiRateLimitPolicyConfig>>;
     signal: AbortSignal;
-    /**
-     * The envelope fields that travel beside the payload, the mock's stand-in
-     * for the server's `res.api(payload, config)`: a mock handler returns its
-     * payload, so this is where the rest of the envelope goes. `logList` is
-     * the usual channel and lives on the context itself.
-     */
-    envelope: {
-        message?: string;
-    };
 };
 /** The same, with the session present: what a `session: true` mock guard and a session endpoint's handler see. */
 export type LambderMockSessionCallContext<S = any> = Omit<LambderMockCallContext<S>, "session"> & {

package/dist/shared/util/LambderTypeUtilities.d.ts

@@ -12,6 +12,24 @@
  * awaits either.
  */
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * T with every object and array readonly, all the way down: what an API
+ * handler's returned answer is checked against.
+ *
+ * An answer is a return value, and TypeScript widens the literals of a
+ * return value whose expected type is still generic (`{ kind: "a" }` reads
+ * as `{ kind: string }`), where a call argument keeps them. The handler's
+ * return is therefore its own `const` type parameter, which keeps literals;
+ * `const` also makes array literals readonly, which a schema's mutable arrays
+ * would refuse, so the bound is this readonly view of the output. Nothing
+ * writes to an answer (it is parsed and sent), so readonly costs nothing.
+ * Functions and Dates pass through whole. Eight levels deep and no further,
+ * because an output may be recursive (`z.json()`), and past that depth the
+ * type is left as it is.
+ */
+export type LambderReadonlyDeep<T, TDepth extends unknown[] = []> = TDepth["length"] extends 8 ? T : T extends (...args: never[]) => unknown ? T : T extends Date ? T : T extends object ? {
+    readonly [K in keyof T]: LambderReadonlyDeep<T[K], [...TDepth, unknown]>;
+} : T;
 /**
  * A declaration map with AT LEAST ONE entry: the union, over every declarable
  * name, of "this one required and the rest optional".

package/dist/shared/wire/LambderAnswerHeaders.d.ts

@@ -21,8 +21,9 @@ export type LambderHeaderTarget = {
     addHeader(key: string, value: string): unknown;
 };
 /**
- * Response headers written while a call runs (`res.setHeader`, `res.addHeader`,
- * the session controller's Set-Cookie), applied onto the answer once the
+ * Response headers written while a call runs (`ctx.setResponseHeader`,
+ * `ctx.addResponseHeader`, `ctx.setCookie`, the session controller's
+ * Set-Cookie), applied onto the answer once the
  * call has one. Recorded as operations in call order rather than as a map,
  * so `set` replaces what the answer itself carries (a Content-Type, say) and
  * `add` appends to it, exactly as if called on the answer directly.

package/dist/shared/wire/LambderAnswerHeaders.js

@@ -36,8 +36,9 @@ export const addAnswerHeader = (headers, name, value) => {
         headers[name] = [value];
 };
 /**
- * Response headers written while a call runs (`res.setHeader`, `res.addHeader`,
- * the session controller's Set-Cookie), applied onto the answer once the
+ * Response headers written while a call runs (`ctx.setResponseHeader`,
+ * `ctx.addResponseHeader`, `ctx.setCookie`, the session controller's
+ * Set-Cookie), applied onto the answer once the
  * call has one. Recorded as operations in call order rather than as a map,
  * so `set` replaces what the answer itself carries (a Content-Type, say) and
  * `add` appends to it, exactly as if called on the answer directly.