lambder 8.3.1 → 9.0.2

package/dist/invoke/LambderInvokeCaller.js

@@ -22,7 +22,7 @@
  */
 import { classifyDeliveryFailure, describeFailure, errorFromFunctionError, LambderInvokeError, parseFunctionError, } from "./LambderInvokeOutcome.js";
 import { DEFAULT_SESSION_TOKEN_COOKIE_KEY } from "../shared/wire/LambderSessionCookieNames.js";
-import { readApiSignature } from "../shared/wire/LambderApiSignature.js";
+import { readApiSignature } from "../shared/wire/LambderApiSignatureMap.js";
 import { resolveApiOutcome } from "../shared/wire/LambderApiOutcome.js";
 import { mergeGuardInputs, } from "../shared/wire/LambderCallOptions.js";
 import { beginIdempotentAttempt, IDEMPOTENT_ATTEMPT_NOT_SENT } from "../shared/wire/LambderIdempotencyKeyScope.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

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { LambderApiResponseConfig } from "../shared/wire/LambderApiContract.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
 import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
@@ -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.

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

@@ -4,7 +4,6 @@
  * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
  */
 import type { LambderCrashDetail } from "./LambderCrashDetail.js";
-import type { LambderNonEmptyOptionMap } from "../util/LambderTypeUtilities.js";
 import type { LambderAppRefusalMessage } from "./LambderApiRefusal.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
 /** Whether an endpoint runs without a session or requires one (addApi versus addSessionApi). */
@@ -32,15 +31,18 @@ export type LambderApiContractShape = Record<string, {
     /** Present when the API declares idempotency: the `idempotency` option exactly as written. */
     idempotency?: LambderApiIdempotencyOption;
 }>;
-/** Envelope flags/channels the server may set beside (or instead of) the payload. */
+/**
+ * Envelope flags and channels beside (or instead of) the payload: what a
+ * refusal, the pipeline's own answers, a hook or an error handler set. An API
+ * handler sets none of them itself: it returns its output or refuses.
+ */
 export type LambderApiResponseConfig = {
     versionExpired?: boolean;
     sessionExpired?: boolean;
     notAuthorized?: boolean;
-    message?: any;
     /**
-     * A refusal message, or a plain string when writing
-     * (`res.api(null, { errorMessage: "..." })`): the envelope goes out with
+     * A refusal message, or a plain string when writing (a refusal thrown
+     * with refuse(), or an error handler's `res.api(null, { errorMessage })`): the envelope goes out with
      * the message object either way. Read off the wire it can still be a
      * string, or no message at all, wherever a Lambder server did not write
      * the body (a hand-built mock answer, a proxy); refusalMessageOf reads
@@ -58,15 +60,8 @@ export type LambderApiResponseConfig = {
     crash?: LambderCrashDetail;
 };
 /**
- * The config a null answer carries: at least one of the reason fields, so
- * `res.api(null, {})` is a compile error. A bare null with no flag and no
- * message reaches the caller as a success whose payload is null, which is
- * indistinguishable from an endpoint that answered nothing on purpose.
- */
-export type LambderApiNullAnswerConfig = LambderNonEmptyOptionMap<Pick<LambderApiResponseConfig, "versionExpired" | "sessionExpired" | "notAuthorized" | "errorMessage" | "message">> & LambderApiResponseConfig;
-/**
- * The API wire envelope both sides speak: res.api() emits it, LambderCaller
- * parses it. `apiVersion` is always there (null when the server set none):
+ * The API wire envelope both sides speak: the server writes it around a
+ * handler's output or a refusal, LambderCaller parses it. `apiVersion` is always there (null when the server set none):
  * it is how a reader tells a Lambder envelope from another JSON answer, such
  * as API Gateway's own `{ "message": ... }` errors, so an answer without it
  * reads as a server failure.

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

@@ -26,10 +26,9 @@ export type LambderApiRefusalOptions = {
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
- * hooks, or nested helpers with no access to the per-request resolver) and
- * the render pipeline maps it onto the structured API envelope
- * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
- * of routing it through setGlobalErrorHandler, so refusals never reach crash
+ * hooks, guards or nested helpers) and the render pipeline maps it onto the
+ * structured API envelope (its errorMessage, notAuthorized and
+ * sessionExpired) instead of routing it through setGlobalErrorHandler, so refusals never reach crash
  * logging and clients receive a parseable response.
  *
  * Thrown outside an API call (e.g. in a route handler) it behaves like any

package/dist/shared/wire/LambderApiRefusal.js

@@ -1,10 +1,9 @@
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
  * crashed". Throw it from anywhere in an API call's call stack (handlers,
- * hooks, or nested helpers with no access to the per-request resolver) and
- * the render pipeline maps it onto the structured API envelope
- * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
- * of routing it through setGlobalErrorHandler, so refusals never reach crash
+ * hooks, guards or nested helpers) and the render pipeline maps it onto the
+ * structured API envelope (its errorMessage, notAuthorized and
+ * sessionExpired) instead of routing it through setGlobalErrorHandler, so refusals never reach crash
  * logging and clients receive a parseable response.
  *
  * Thrown outside an API call (e.g. in a route handler) it behaves like any

package/dist/testing/LambderTestVisitor.d.ts

@@ -5,7 +5,7 @@ import { type LambderLambdaHttpResult } from "../invoke/LambderLambdaEvent.js";
 import type { LambderCreatedSession } from "../session/LambderSessionManager.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
-import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
+import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { LambderGuardInputsProviderOption } from "../shared/wire/LambderCallOptions.js";
 /**
  * How one visitor differs from the next. Everything is optional: a visitor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "8.3.1",
+  "version": "9.0.2",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [