lambder 15.0.2 → 15.1.1

package/CHANGELOG.md

@@ -9,6 +9,32 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [15.1.1] - 2026-10-03
+
+A minor: every request a route answers writes a call summary line, named by
+the route as registered, and a matcher object can name its route.
+
+### Added
+
+- **A call summary line for every route.** A request a route answered
+  (`addRoute`, `addSessionRoute`, or an `addAction` on its HTTP side) writes
+  the same `lambder.call` line an API call does, so a webhook or a page route
+  is counted, timed and queried beside the endpoints. The line's `route`
+  names the route as it was registered, its matcher's `name` or its method
+  and path pattern, and carries nothing of the request's own path; its
+  `outcome` is read from its status (`success` below 400, `crash` from 500,
+  `other` between) and `handlerMs` is the route handler's own time. A line
+  a hook's answer ends in is the matched route's too. Files, the index page,
+  the route fallback and non-HTTP events still write none.
+- **`name` on a matcher object**, what the line names the route by, which a
+  bare predicate route needs to be named at all.
+
+### Changed
+
+- **`LambderCallSummary.api` is null for a route, and the line gains
+  `route`**, null for an API call. A `callSummary` function that read `api`
+  as a string narrows it first.
+
 ## [15.0.2] - 2026-10-02
 
 A patch: two fixes for apps with a large contract.

package/README.md

@@ -80,10 +80,10 @@ const company = await caller.companies.get({ slug: "acme" });
   cookies, and a guard against Lambda's response size cap.
 - **Hooks and actions.** Lifecycle hooks, plus `addAction()` for the non-HTTP
   invocations (EventBridge, SQS, custom events) the same function receives.
-- **A summary line per call.** Every API call is logged once, as JSON, with
-  its endpoint, outcome, refusal code, status and timings, and the request
-  ids that join it to the calls it made; nothing from its input or its
-  caller.
+- **A summary line per call.** Every API call, and every request a route
+  answers, is logged once, as JSON, with its endpoint or route, outcome,
+  refusal code, status and timings, and the request ids that join it to the
+  calls it made; nothing from its input, its path or its caller.
 - **Lambda to lambda calls.** `LambderInvokeCaller` invokes a Lambder app in
   another function directly, with no API Gateway in between, typed from the
   callee's own contract and carrying its refusals, crash detail and logs back.

package/dist/core/Lambder.d.ts

@@ -150,7 +150,7 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     private readonly trustedClientIpHeaders;
     private readonly trustedHostHeaders;
     private readonly originProof;
-    /** Where each API call's summary goes (the callSummary option); null writes none. Replaceable through the backend swap alone. */
+    /** Where each call's summary goes, an API call's or a route's (the callSummary option); null writes none. Replaceable through the backend swap alone. */
     private callSummaryWriter;
     constructor(given?: LambderCreateOptions<TApp["session"]>);
     setRouteFallbackHandler(routeFallbackHandler: LambderFallbackHandler): this;
@@ -464,8 +464,8 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     private resolveRequest;
     /**
      * One HTTP invocation, from the event to the finalized response, under
-     * an invocation record of its own (see LambderInvocationScope): what an
-     * API call's summary line is written from once the response is final.
+     * an invocation record of its own (see LambderInvocationScope): what its
+     * call summary line is written from once the response is final.
      */
     render(event: LambderHttpEvent, lambdaContext: Context): Promise<LambderHttpResponse>;
     private renderRequest;
@@ -496,9 +496,9 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      */
     private answerCrash;
     /**
-     * The summary line of an API call, once its response is final: nothing
-     * for an invocation that served no API call. A writer that throws costs
-     * the call its line and nothing else.
+     * The summary line of an API call or of a request a route answered, once
+     * its response is final: nothing for an invocation that served neither. A
+     * writer that throws costs the call its line and nothing else.
      */
     private writeCallSummary;
     /**

package/dist/core/Lambder.js

@@ -1,7 +1,7 @@
 import LambderResolver from "./LambderResolver.js";
 import LambderResponseBuilder from "./LambderResponseBuilder.js";
 import { LambderResponse, finalizeResponse, answerFromResponse, responseFromAnswer, emitResponse, DEFAULT_FINALIZE_OPTIONS, DEFAULT_RESPONSE_COMPRESSION_SETTINGS, } from "./LambderResponse.js";
-import { compileRouteMatcher } from "./LambderRouting.js";
+import { compileRouteMatcher, routeNameOf } from "./LambderRouting.js";
 import { allowedCorsOriginOf, applyCorsHeaders } from "./LambderCors.js";
 import LambderSessionManager from "../session/LambderSessionManager.js";
 import { resolveCompressionOption } from "../shared/wire/LambderCompressionOption.js";
@@ -37,7 +37,7 @@ import { assertCreateOptions, mergeNamedMaps, } from "./LambderCreateOptions.js"
 /** The refusals of a name no API is registered under: no code, and none required. */
 const NO_DECLARED_REFUSALS = { codes: new Map(), codeRequired: false };
 /** Longest endpoint name a call summary carries: a page built before paths posts the name in its body, and a line is no place for a long one. */
-const MAX_SUMMARY_API_NAME_CHARS = 200;
+const MAX_SUMMARY_NAME_CHARS = 200;
 /** A request id as the parent header may carry one: what Lambda's own ids look like, and no longer than any of them. */
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9-]{1,128}$/;
 /**
@@ -52,7 +52,11 @@ const parentRequestIdOf = (event) => {
     return typeof value === "string" && REQUEST_ID_PATTERN.test(value) ? value : null;
 };
 /** The API call a request is, as its invocation records it; null for a request that is no API call. */
-const apiCallOf = (ctx, event) => ctx.api ? { api: ctx.api.apiName, parentRequestId: parentRequestIdOf(event) } : null;
+const apiCallOf = (ctx, event) => ctx.api ? { api: ctx.api.apiName, route: null, parentRequestId: parentRequestIdOf(event) } : null;
+/** The call a request a route answered is: the route by its registered name, never by the path asked for. */
+const routeCallOf = (ctx, route) => ({ api: null, route, parentRequestId: parentRequestIdOf(ctx.event) });
+/** A route's outcome, which no envelope names: read from the status it answered with, as an API call's 5xx reads. */
+const outcomeOfStatus = (status) => ({ outcome: status >= 500 ? "crash" : status >= 400 ? "other" : "success", code: null });
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -157,7 +161,7 @@ export default class Lambder {
     trustedClientIpHeaders;
     trustedHostHeaders;
     originProof;
-    /** Where each API call's summary goes (the callSummary option); null writes none. Replaceable through the backend swap alone. */
+    /** Where each call's summary goes, an API call's or a route's (the callSummary option); null writes none. Replaceable through the backend swap alone. */
     callSummaryWriter;
     constructor(given = {}) {
         // The guards and the rate-limit policies as one map each, whether
@@ -314,6 +318,7 @@ export default class Lambder {
     addRoute(condition, actionFn) {
         this.actionList.push({
             match: compileRouteMatcher(condition),
+            name: routeNameOf(condition),
             actionFn: (ctx, resolver) => actionFn(ctx, resolver),
         });
         return this;
@@ -321,6 +326,7 @@ export default class Lambder {
     addSessionRoute(condition, actionFn) {
         this.actionList.push({
             match: compileRouteMatcher(condition),
+            name: routeNameOf(condition),
             actionFn: async (ctx, resolver) => {
                 await this.requireSession(ctx, resolver);
                 // requireSession answered already if there was no session, so
@@ -429,6 +435,7 @@ export default class Lambder {
                 const group = ctx.api ? splitApiName(ctx.api.apiName)?.group : undefined;
                 return group !== undefined && names.has(group) ? {} : false;
             },
+            name: null,
             actionFn: (ctx, resolver) => instance.dispatchApiCall(ctx, resolver),
         });
         return instance;
@@ -556,6 +563,7 @@ export default class Lambder {
         // HTTP side: joins the route/API chain in registration order.
         this.actionList.push({
             match: (ctx) => filter(ctx.event, ctx) ? {} : false,
+            name: null,
             actionFn: async (ctx, resolver) => {
                 const result = await actionFn(ctx.event, { ctx, res: resolver, lambdaContext: ctx.lambdaContext });
                 if (!(result instanceof LambderResponse)) {
@@ -919,15 +927,32 @@ export default class Lambder {
         // Set before the hooks run, so a beforeRender hook on a matched route
         // sees the route's own path params.
         ctx.pathParams = matched.params;
+        // A route's call is named as soon as it has matched, before the hooks
+        // run, so the line a hook's answer ends in is the route's too. An API
+        // call keeps the name its path gave it, whatever action answers it.
+        const invocation = currentInvocation();
+        if (invocation && !invocation.call)
+            invocation.call = routeCallOf(ctx, matched.action.name);
         const beforeRenderResult = await this.runBeforeRenderHooks(ctx, resolver, onContextReplaced);
         if (beforeRenderResult instanceof LambderResponse)
             return beforeRenderResult;
-        return await matched.action.actionFn(beforeRenderResult, resolver);
+        // An API call's handler time is the pipeline's to measure, inside its
+        // own work; a route's is the whole action.
+        if (ctx.api)
+            return await matched.action.actionFn(beforeRenderResult, resolver);
+        const handlerStarted = performance.now();
+        try {
+            return await matched.action.actionFn(beforeRenderResult, resolver);
+        }
+        finally {
+            if (invocation)
+                invocation.handlerMs = performance.now() - handlerStarted;
+        }
     }
     /**
      * One HTTP invocation, from the event to the finalized response, under
-     * an invocation record of its own (see LambderInvocationScope): what an
-     * API call's summary line is written from once the response is final.
+     * an invocation record of its own (see LambderInvocationScope): what its
+     * call summary line is written from once the response is final.
      */
     async render(event, lambdaContext) {
         return await runInvocation(lambdaContext, async (invocation) => {
@@ -995,7 +1020,8 @@ export default class Lambder {
             // reach it.
             ctx.responseHeaders.applyTo(response, response === responseIntoHooks ? headersAppliedIntoHooks : 0);
             this.applyCors(allowedOrigin, response, this.isCorsPreflight(ctx));
-            invocation.outcome = response.callOutcome ?? { outcome: "other", code: null };
+            // An API answer names its outcome; a route's answer names none, and reads from its status.
+            invocation.outcome = response.callOutcome ?? (ctx.api ? { outcome: "other", code: null } : outcomeOfStatus(response.statusCode));
             return await finalizeResponse(ctx, response, this.finalizeOptions, ctx.eventFormat);
         }
         catch (err) {
@@ -1101,9 +1127,9 @@ export default class Lambder {
         return emitResponse(eventFormat, crashResponse.statusCode, crashResponse.headers, typeof crashResponse.body === "string" ? crashResponse.body : "", false);
     }
     /**
-     * The summary line of an API call, once its response is final: nothing
-     * for an invocation that served no API call. A writer that throws costs
-     * the call its line and nothing else.
+     * The summary line of an API call or of a request a route answered, once
+     * its response is final: nothing for an invocation that served neither. A
+     * writer that throws costs the call its line and nothing else.
      */
     writeCallSummary(invocation, status) {
         const { call } = invocation;
@@ -1112,8 +1138,10 @@ export default class Lambder {
         const summary = {
             kind: "lambder.call",
             // The path form is two identifiers; a page built before paths
-            // posts the name in its body, which is whatever it sent.
-            api: call.api.slice(0, MAX_SUMMARY_API_NAME_CHARS),
+            // posts the name in its body, which is whatever it sent. A route's
+            // name is the app's own, cut the same way.
+            api: call.api === null ? null : call.api.slice(0, MAX_SUMMARY_NAME_CHARS),
+            route: call.route === null ? null : call.route.slice(0, MAX_SUMMARY_NAME_CHARS),
             outcome: invocation.outcome?.outcome ?? "other",
             code: invocation.outcome?.code ?? null,
             status,
@@ -1128,7 +1156,7 @@ export default class Lambder {
             this.callSummaryWriter(summary);
         }
         catch (err) {
-            console.error(`Lambder: the callSummary writer threw, so the summary of "${summary.api}" was not written. ${coerceToError(err).message}`);
+            console.error(`Lambder: the callSummary writer threw, so the summary of "${summary.api ?? summary.route ?? "a route"}" was not written. ${coerceToError(err).message}`);
         }
     }
     /**

package/dist/core/LambderCallSummary.d.ts

@@ -1,17 +1,19 @@
 import type { LambderCallOutcome } from "../shared/wire/LambderCallOutcome.js";
 /**
- * One API call as its summary line records it: what was called, how it
- * ended, how long it took, and the ids that join it to the rest of the
- * logs. Nothing from the call's input, its session, its cookies or its
- * caller's address is in it, so the line can be kept and queried as long as
- * the app likes.
+ * One API call, or one request a route answered, as its summary line records
+ * it: what was called, how it ended, how long it took, and the ids that join
+ * it to the rest of the logs. Nothing from the call's input, its path, its
+ * session, its cookies or its caller's address is in it, so the line can be
+ * kept and queried as long as the app likes.
  */
 export type LambderCallSummary = {
     /** Always "lambder.call": what a log query picks the lines out by. */
     kind: "lambder.call";
-    /** The endpoint the call's path named (`group.action`), whether or not one is registered under it. */
-    api: string;
-    /** How the call ended; see LambderCallOutcome. */
+    /** The endpoint an API call's path named (`group.action`), whether or not one is registered under it; null for a route. */
+    api: string | null;
+    /** The route that answered, as it was registered: its matcher's name, or its method and path pattern; null for an API call, for a predicate route given no name, and for an addAction that answered an HTTP request. */
+    route: string | null;
+    /** How the call ended; see LambderCallOutcome. A route's is read from its status: success below 400, crash from 500, other between. */
     outcome: LambderCallOutcome;
     /** The refusal's code, the framework's (`lambder/rate-limited`) or the app's; null when the answer carries none. */
     code: string | null;
@@ -19,7 +21,7 @@ export type LambderCallSummary = {
     status: number;
     /** From the invocation's start to the answer, in milliseconds. */
     durationMs: number;
-    /** How long the API handler itself ran, in milliseconds; null when it did not run (refused before it, or replayed). */
+    /** How long the API handler, or the route's handler, itself ran, in milliseconds; null when it did not run (refused before it, replayed, or answered by a hook). */
     handlerMs: number | null;
     /** True when a stored idempotent answer was replayed and no handler ran. */
     replayed: boolean;

package/dist/core/LambderCreateOptions.d.ts

@@ -292,14 +292,15 @@ export type LambderCreateOptions<TSessionData = any> = {
      */
     originProof?: LambderOriginProof;
     /**
-     * One summary per API call, written when the call is answered: the
-     * endpoint, how it ended (success, a refusal and its code, a flag, a
-     * validation refusal, a crash), the status, the duration and the
-     * handler's own time, whether an idempotent answer was replayed, whether
-     * the invocation was the process's first, and its request id with the
-     * id of the invocation that called it over invoke. Nothing from the
-     * input, the session, the cookies or the caller's address. See
-     * LambderCallSummary.
+     * One summary per API call, and per request a route answered, written
+     * when it is answered: the endpoint or the route as registered, how it
+     * ended (success, a refusal and its code, a flag, a validation refusal, a
+     * crash; a route's read from its status), the status, the duration and
+     * the handler's own time, whether an idempotent answer was replayed,
+     * whether the invocation was the process's first, and its request id
+     * with the id of the invocation that called it over invoke. Nothing from
+     * the input, the path, the session, the cookies or the caller's address.
+     * See LambderCallSummary.
      *
      * Default: each summary as one JSON line on stdout, which a Lambda
      * function's log group keeps and CloudWatch Logs Insights reads field by

package/dist/core/LambderInvocationScope.d.ts

@@ -7,13 +7,19 @@ export type LambderInvocationRecord = LambderInvocation & {
     readonly startedAt: number;
     /** Whether this is the first invocation this process has run. */
     readonly coldStart: boolean;
-    /** How long the API handler itself ran, in milliseconds; null until it has. */
+    /** How long the API handler, or the route's handler, itself ran, in milliseconds; null until it has. */
     handlerMs: number | null;
     /** Whether an idempotent answer was replayed, so no handler ran. */
     replayed: boolean;
-    /** The API call the invocation serves: the endpoint its path named, and the invocation that invoked it, when one did. Null for anything else. */
+    /**
+     * What the invocation serves, named: an API call by the endpoint its path
+     * named, or a request a route answered by the route as registered (null
+     * for a route with no name), with the invocation that invoked it, when
+     * one did. Null for anything else: a file, the index page, an event.
+     */
     call: {
-        api: string;
+        api: string | null;
+        route: string | null;
         parentRequestId: string | null;
     } | null;
     /** What the answer is, once the call has one. */

package/dist/core/LambderRouting.d.ts

@@ -15,6 +15,8 @@ export type LambderRouteMatcher = {
     /** One or more HTTP methods; HEAD requests also match GET routes. */
     method?: string | string[];
     condition?: LambderRouteConditionFn;
+    /** What the route's call summary line names it by; by default its method and path pattern, which a route with neither has none of. */
+    name?: string;
 };
 export type LambderRouteCondition = LambderRoutePath | RegExp | LambderRouteConditionFn | LambderRouteMatcher;
 /** Returns matched path params, or false when the route doesn't match. */
@@ -28,6 +30,13 @@ export type CompiledMatcher = (ctx: LambderRenderContext) => false | Record<stri
  * this rule, so neighbouring slots cannot disagree about what a method means.
  */
 export declare const allowsRequestMethod: (methods: ReadonlySet<string>, requestMethod: string) => boolean;
+/**
+ * What a route's call summary line names it by: the name its matcher gives,
+ * or its method and path pattern, both fixed at registration, so the line
+ * carries nothing of the request's own path. Null for a route with neither,
+ * a bare predicate, which the line still counts.
+ */
+export declare const routeNameOf: (condition: LambderRouteCondition) => string | null;
 /** Compile a route condition once at registration time. */
 export declare const compileRouteMatcher: (condition: LambderRouteCondition) => CompiledMatcher;
 export {};

package/dist/core/LambderRouting.js

@@ -57,6 +57,26 @@ export const allowsRequestMethod = (methods, requestMethod) => {
         return true;
     return method === "HEAD" && methods.has("GET");
 };
+/**
+ * What a route's call summary line names it by: the name its matcher gives,
+ * or its method and path pattern, both fixed at registration, so the line
+ * carries nothing of the request's own path. Null for a route with neither,
+ * a bare predicate, which the line still counts.
+ */
+export const routeNameOf = (condition) => {
+    if (typeof condition === "string")
+        return condition;
+    if (condition instanceof RegExp)
+        return condition.toString();
+    if (typeof condition === "function")
+        return null;
+    if (condition.name !== undefined)
+        return condition.name;
+    const methods = condition.method === undefined ? [] : (Array.isArray(condition.method) ? condition.method : [condition.method]).map((m) => m.toUpperCase());
+    const path = condition.path === undefined ? null : typeof condition.path === "string" ? condition.path : condition.path.toString();
+    const name = [methods.join(","), path].filter((part) => part).join(" ");
+    return name || null;
+};
 /** Compile a route condition once at registration time. */
 export const compileRouteMatcher = (condition) => {
     if (typeof condition === "string" || condition instanceof RegExp) {

package/dist/testing/LambderTestApp.d.ts

@@ -153,9 +153,10 @@ export declare class LambderTestApp<TContract extends LambderApiContractShape =
      */
     get crashes(): readonly Error[];
     /**
-     * The summary of every API call the app answered since the last reset,
-     * in order (see LambderCallSummary): what its callSummary option would
-     * have been handed, collected here instead of written to stdout.
+     * The summary of every API call, and every request a route answered,
+     * since the last reset, in order (see LambderCallSummary): what the app's
+     * callSummary option would have been handed, collected here instead of
+     * written to stdout.
      */
     get callSummaries(): readonly LambderCallSummary[];
     /**

package/dist/testing/LambderTestApp.js

@@ -183,9 +183,10 @@ export class LambderTestApp {
         return this.crashList;
     }
     /**
-     * The summary of every API call the app answered since the last reset,
-     * in order (see LambderCallSummary): what its callSummary option would
-     * have been handed, collected here instead of written to stdout.
+     * The summary of every API call, and every request a route answered,
+     * since the last reset, in order (see LambderCallSummary): what the app's
+     * callSummary option would have been handed, collected here instead of
+     * written to stdout.
      */
     get callSummaries() {
         return this.callSummaryList;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "15.0.2",
+  "version": "15.1.1",
   "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": [