lambder 15.0.2 → 16.0.1

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";
@@ -13,7 +13,7 @@ import { LambderFiles } from "./LambderFiles.js";
 import { isLambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
 import { LambderApiPipeline } from "../api/LambderApiPipeline.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
-import { declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
+import { assertRefusalCodesDeclared, declaredRefusalVocabulary, readRefusalVocabulary, resolveAllowedRefusals, toRefusalCodes, } from "../api/LambderApiRefusals.js";
 import { refuse } from "../shared/wire/LambderApiRefusal.js";
 import { apiSignatureOf } from "../api/LambderApiSignature.js";
 import { apiNameKeyOf } from "../shared/wire/LambderApiSignatureMap.js";
@@ -22,7 +22,10 @@ import { apiNotFoundAnswer, envelopeAnswer, sessionExpiredAnswer, successEnvelop
 import { describePayloadKind, isObjectPayload } from "../shared/wire/LambderObjectPayload.js";
 import { LambderApiOutputValidationError } from "../api/LambderApiOutputValidationError.js";
 import { toGuardEntries } from "../api/LambderApiGuards.js";
-import { buildApiGroup, buildLazyApiGroup, isRegistrableApiGroup, } from "../api/LambderApiDeclarations.js";
+import { apiModuleDeclarationsOf } from "../api/LambderApiModules.js";
+import { apiModuleUsesOf, isRegistrableApiGroup, } from "../api/LambderApiDeclarations.js";
+import { apiBuildersFor, } from "./LambderApiBuilders.js";
+import { LambderApiModule, } from "./LambderApiModule.js";
 import { splitApiName } from "../shared/wire/LambderApiNames.js";
 import { bindContextTools, createContext, isV2HttpEvent, } from "./LambderContext.js";
 import { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD } from "../shared/wire/LambderRequestPayload.js";
@@ -36,8 +39,10 @@ import { policyBuildersFor } from "./LambderPolicyBuilders.js";
 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 };
+/** The instance's own declaration builders: no module, and nothing of any instance, so every instance hands out the same three functions, each typed on its own app types. */
+const INSTANCE_BUILDERS = apiBuildersFor(null);
 /** 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 +57,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
@@ -124,9 +133,14 @@ export default class Lambder {
     apiGroupNames = new Set();
     /** The lazy groups not loaded yet, each with its load in progress, if one is. */
     lazyApiGroups = new Map();
-    /** The guards given at creation, merged into one map, kept for apiSignatures(): a guard's schema is part of the signature of every endpoint declaring it. */
+    /**
+     * The guards given at creation merged into one map, and every registered
+     * module's beside them, kept for registration (a guard's session and
+     * refusal codes), apiSignatures() (a guard's schema is part of the
+     * signature of every endpoint declaring it) and apiOptionEntries().
+     */
     guards;
-    /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
+    /** The rate-limit policies given at creation, and every registered module's beside them, kept for apiOptionEntries(), which records each one less its key handler. */
     rateLimitPolicies;
     /** The refusal vocabulary given at creation: what each API's and each guard's refusal codes resolve against. Null without the option. */
     refusalVocabulary;
@@ -157,7 +171,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
@@ -166,7 +180,10 @@ export default class Lambder {
         const options = {
             ...given,
             guards: given.guards && mergeNamedMaps(given.guards, "guard"),
-            rateLimits: given.rateLimits && { ...given.rateLimits, policies: mergeNamedMaps(given.rateLimits.policies, "rate-limit policy") },
+            rateLimits: given.rateLimits && {
+                ...given.rateLimits,
+                policies: given.rateLimits.policies === undefined ? undefined : mergeNamedMaps(given.rateLimits.policies, "rate-limit policy"),
+            },
         };
         assertCreateOptions(options);
         this.files = options.files ? new LambderFiles(options.files) : null;
@@ -185,8 +202,8 @@ export default class Lambder {
             this.corsConfig = options.cors === true ? {} : options.cors;
         }
         const session = options.session;
-        this.guards = options.guards;
-        this.rateLimitPolicies = options.rateLimits?.policies;
+        this.guards = { ...options.guards };
+        this.rateLimitPolicies = { ...options.rateLimits?.policies };
         this.refusalVocabulary = readRefusalVocabulary(options.refusals);
         this.pipeline = new LambderApiPipeline({
             apiVersion: this.apiVersion,
@@ -314,6 +331,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 +339,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
@@ -335,46 +354,56 @@ export default class Lambder {
     // Declared as values, gathered into named groups, registered in one call.
     // =====================================================================
     /**
-     * Declares one endpoint, typed on this instance's types: its input and
-     * output schemas, its guards, rate limits, idempotency and refusals, and
-     * its handler. Nothing is registered until the declaration is put in a
-     * group (defineApiGroup) and the group is registered (registerApiGroups).
+     * Declares one endpoint, typed on this instance's types (see
+     * LambderDefineApi). Nothing is registered until the declaration is put
+     * in a group (defineApiGroup) and the group is registered
+     * (registerApiGroups).
      *
-     * The guards say who may call it, and so its mode: an endpoint whose
-     * guards include one that needs a session (`session: true`) is a session
-     * endpoint, its session read before the guards run and a call without
-     * one answered sessionExpired, and its handler's ctx.session is typed
-     * present. Any other endpoint is public.
-     *
-     * An arrow property rather than a method, so an app can hand it out
-     * detached: `export const { defineApi, defineApiGroup } = lambderApp;`.
+     * An arrow property rather than a method, as are the two below, so an
+     * app can hand them out detached; handed out under the instance's name
+     * (`export const defineApi: AppLambder["defineApi"] = lambderApp.defineApi`),
+     * a declaration file names each by the instance's type rather than
+     * writing the app's types out again in each.
      */
-    defineApi = (options, 
-    /** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
-    handler) => ({ kind: "lambderApi", options: options, handler: handler });
+    defineApi = INSTANCE_BUILDERS.defineApi;
+    /** Gathers endpoints into a named group (see LambderDefineApiGroup). */
+    defineApiGroup = INSTANCE_BUILDERS.defineApiGroup;
+    /** A group loaded on the first call to one of its endpoints (see LambderDefineLazyApiGroup). */
+    lazyApiGroup = INSTANCE_BUILDERS.lazyApiGroup;
     /**
-     * Gathers endpoints into a named group: each is registered as
-     * `name.action` and called at `{apiPath}/{name}/{action}`, and every
-     * Lambder caller reaches it as `caller.name.action(input)`. A group's
-     * name and its actions are identifiers, and a group may not take a name
-     * a caller already answers for (see LAMBDER_RESERVED_GROUP_NAMES).
+     * Defines a module: guards and rate-limit policies a part of the app
+     * declares for its own endpoints, beside the ones this instance was
+     * created with. Returns the module's builders, whose endpoints may name
+     * the instance's guards and policies and the module's own, and nothing
+     * else; their groups are registered with registerApiGroups() as any
+     * are, and their registration adds the module's guards and policies to
+     * the instance that registers them.
      *
-     * A group declared across files takes each file's part:
-     * `defineApiGroup("orders", orderReadApis, orderWriteApis)`. An action
-     * two parts declare is refused, at compile time and at startup, rather
-     * than one silently replacing the other as an object spread would.
-     */
-    defineApiGroup = (name, ...parts) => buildApiGroup(name, parts);
-    /**
-     * A group loaded on the first call to one of its endpoints:
-     * `lazyApiGroup("orders", () => import("./orders.js").then((m) => m.orderApis))`.
-     * A cold start then parses none of it, nor anything only it imports,
-     * until a request calls it; the contract is the loaded group's, read off
-     * its type. The group loaded must carry the same name, which the type
-     * checks and loading checks again. `loadApiGroups()` loads every group,
-     * for a build step or a boot check that has to see them all.
+     * ```typescript
+     * export const giftCardModule = storeApp.defineApiModule({
+     *     guards: { cardHolder },
+     *     rateLimitPolicies: { redeemPerCard: { perHour: 5, per: "session" } },
+     * });
+     * ```
+     *
+     * A name the instance declares is refused here, at compile time and at
+     * the call; a name two modules declare is refused when the second is
+     * registered, as create() refuses a name two maps declare. A module's
+     * rate-limit policies count on the instance's limiter, so they need the
+     * rateLimits option at creation, whose own policies may then be left out.
      */
-    lazyApiGroup = (name, load) => buildLazyApiGroup(name, load);
+    defineApiModule(options) {
+        const given = options;
+        const declarations = apiModuleDeclarationsOf(given, "Lambder");
+        for (const [name, guard] of Object.entries(declarations.guards)) {
+            assertRefusalCodesDeclared(`guard "${name}"`, (guard?.refusals ?? []), this.refusalVocabulary);
+        }
+        // Checked against this instance now, so a name it declares fails
+        // where the module is defined; registration checks again against
+        // whichever instance takes the module, and against the other modules.
+        this.pipeline.modulesToAdd([{ module: declarations, usedBy: "being defined" }]);
+        return new LambderApiModule(declarations);
+    }
     /**
      * Registers groups of endpoints, as one contract: `typeof
      * lambder.ApiContract` then maps every `group.action` to its entry, one
@@ -405,7 +434,6 @@ export default class Lambder {
         // caller that catches the error and fixes the declaration is told the
         // real problem on its next try.
         const names = new Set();
-        const prepared = [];
         for (const group of groups) {
             if (!isRegistrableApiGroup(group)) {
                 throw new Error("Lambder: registerApiGroups takes groups built by defineApiGroup() or lazyApiGroup().");
@@ -414,10 +442,21 @@ export default class Lambder {
                 throw new Error(`Lambder: group "${group.name}" is registered twice. A group is one namespace, so its endpoints belong in one defineApiGroup().`);
             }
             names.add(group.name);
+        }
+        // The modules the groups bring, a lazy group's at once: checked
+        // against the instance and each other here, taken only after every
+        // endpoint passed against them.
+        const registrable = groups;
+        const added = instance.pipeline.modulesToAdd(registrable.flatMap(apiModuleUsesOf));
+        const prepared = [];
+        for (const group of registrable) {
             if (group.kind === "lambderApiGroup")
-                prepared.push(...instance.prepareApiGroup(group));
+                prepared.push(...instance.prepareApiGroup(group, added));
         }
-        for (const group of groups) {
+        instance.pipeline.addModules(added);
+        instance.guards = { ...instance.guards, ...added.guards };
+        instance.rateLimitPolicies = { ...instance.rateLimitPolicies, ...added.rateLimitPolicies };
+        for (const group of registrable) {
             instance.apiGroupNames.add(group.name);
             if (group.kind === "lambderLazyApiGroup")
                 instance.lazyApiGroups.set(group.name, { group, loading: null });
@@ -429,6 +468,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;
@@ -471,9 +511,14 @@ export default class Lambder {
             await this.loadLazyApiGroup(group);
         return this.apiDefinitions.get(apiName);
     }
-    /** The endpoints of one group, each checked as `group.action`; nothing is registered until they are committed. */
-    prepareApiGroup(group) {
-        return Object.entries(group.apis).map(([action, declaration]) => this.prepareApi(`${group.name}.${action}`, declaration.options, declaration.handler));
+    /**
+     * The endpoints of one group, each checked as `group.action` against the
+     * instance's guards and policies and those `adding` holds, of the modules
+     * the same registration adds; nothing is registered until they are
+     * committed.
+     */
+    prepareApiGroup(group, adding) {
+        return Object.entries(group.apis).map(([action, declaration]) => this.prepareApi(`${group.name}.${action}`, declaration.options, declaration.handler, adding));
     }
     /**
      * A lazy group, loaded once: its import, checked to be the group it was
@@ -494,6 +539,16 @@ export default class Lambder {
                 if (loaded.name !== name) {
                     throw new Error(`Lambder: lazy group "${name}" loaded the group "${loaded.name}". The loader must resolve to the group of the name it was registered under.`);
                 }
+                // A module's guards and policies are added when its group is
+                // registered, at startup, so a collision fails the boot and a
+                // route charging one of its policies finds it from the first
+                // request; one first met here would do neither.
+                for (const { module } of apiModuleUsesOf(loaded)) {
+                    if (!this.pipeline.hasModule(module)) {
+                        throw new Error(`Lambder: lazy group "${name}" loaded endpoints a module's builders declared, and was registered with a lazyApiGroup that does not carry that module. ` +
+                            `Register it with the module's own lazyApiGroup, so its guards and rate-limit policies are added at startup.`);
+                    }
+                }
                 for (const api of this.prepareApiGroup(loaded))
                     this.commitApi(api);
                 this.lazyApiGroups.delete(name);
@@ -510,9 +565,12 @@ export default class Lambder {
      * digests, beside its handler. Nothing is recorded here (commitApi does
      * that), so a refusal anywhere in a registration leaves nothing behind.
      */
-    prepareApi(name, schema, handler) {
+    prepareApi(name, schema, handler, adding) {
         const guardEntries = toGuardEntries(schema.guards);
-        const guardNeedsSession = (guard) => !!this.guards && Object.prototype.hasOwnProperty.call(this.guards, guard) && this.guards[guard]?.session === true;
+        const guardOf = (guard) => Object.prototype.hasOwnProperty.call(this.guards, guard) ? this.guards[guard]
+            : adding && Object.prototype.hasOwnProperty.call(adding.guards, guard) ? adding.guards[guard]
+                : undefined;
+        const guardNeedsSession = (guard) => guardOf(guard)?.session === true;
         const mode = guardEntries.some(({ name: guard }) => guardNeedsSession(guard)) ? "session" : "public";
         if (mode === "session" && !this.pipeline.hasSessions) {
             throw new Error(`Lambder: a guard of API "${name}" needs a session, and the instance was created without the session option.`);
@@ -527,13 +585,10 @@ export default class Lambder {
         if (schema.refusals !== undefined && ownRefusals.length === 0) {
             throw new Error(`Lambder: API "${name}" declares an empty refusals option, which declares no code. Name the codes it refuses with, or omit the option entirely.`);
         }
-        const allowedCodes = resolveAllowedRefusals(name, this.refusalVocabulary, ownRefusals, guardEntries.map(({ name: guard }) => ({
-            guard,
-            codes: (this.guards && Object.prototype.hasOwnProperty.call(this.guards, guard) ? this.guards[guard]?.refusals : undefined) ?? [],
-        })));
+        const allowedCodes = resolveAllowedRefusals(name, this.refusalVocabulary, ownRefusals, guardEntries.map(({ name: guard }) => ({ guard, codes: guardOf(guard)?.refusals ?? [] })));
         const refusals = { codes: allowedCodes, codeRequired: this.requireRefusalCodes };
         const definition = { name, mode, guards: schema.guards, rateLimit: schema.rateLimit, idempotency: schema.idempotency, input: schema.input, output: schema.output, refusals };
-        this.pipeline.assertRegistration(definition);
+        this.pipeline.assertRegistration(definition, adding);
         return { definition, refusalsOption: schema.refusals, output: schema.output, compress: schema.compress ?? "auto", handler };
     }
     /** Records a checked endpoint: its definition, its refusals option as written, and what answers it. */
@@ -556,6 +611,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)) {
@@ -695,7 +751,7 @@ export default class Lambder {
             apis[name] = entry;
         }
         const rateLimitPolicies = {};
-        for (const name of Object.keys(this.rateLimitPolicies ?? {}).sort()) {
+        for (const name of Object.keys(this.rateLimitPolicies).sort()) {
             const { per, budget, chargeAt, refusal, ...windows } = this.rateLimitPolicies[name];
             const entry = {};
             for (const [window, limit] of Object.entries(windows)) {
@@ -715,7 +771,7 @@ export default class Lambder {
             rateLimitPolicies[name] = entry;
         }
         const guards = {};
-        for (const name of Object.keys(this.guards ?? {}).sort()) {
+        for (const name of Object.keys(this.guards).sort()) {
             const guard = this.guards[name];
             guards[name] = {
                 input: guard.apiInput ? "apiInput" : guard.guardInput ? "guardInput" : "none",
@@ -919,15 +975,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 +1068,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 +1175,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 +1186,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 +1204,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/LambderApiBuilders.d.ts

@@ -0,0 +1,105 @@
+import type { z } from "zod";
+import type { LambderRenderContext, LambderSessionRenderContext } from "./LambderContext.js";
+import type { LambderObjectOutputCheck, LambderPayloadSliceCheck, LambderRequirableGuardsField } from "./LambderCreateOptions.js";
+import type { LambderReadonlyDeep, LambderMaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderDeclaredRefuse } from "../shared/wire/LambderApiRefusal.js";
+import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
+import type { LambderContractEntry, LambderJsonOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusalNamesOf, LambderGuardsOption } from "../api/LambderApiGuards.js";
+import type { LambderRateLimitOption } from "../api/LambderApiRateLimits.js";
+import type { LambderHandlerRefusalsOf, LambderRefusalNamesIn, LambderRefusalsOption, LambderWireRefusalsOf } from "../api/LambderApiRefusals.js";
+import type { LambderApiModuleDeclarations } from "../api/LambderApiModules.js";
+import { type LambderActionNamesCheck, type LambderApiDeclaration, type LambderApiDeclarations, type LambderApiGroup, type LambderApiModeOf, type LambderAppTypes, type LambderGroupNameCheck, type LambderGroupPartsCheck, type LambderLazyApiGroup, type LambderMergedParts, type LambderPublicSessionPolicyCheck, type LambderSessionModeCheck } from "../api/LambderApiDeclarations.js";
+/** The codes one API may refuse with, typed: its own refusals option's and its declared guards', as the vocabulary holds them. */
+export type LambderApiRefusalCodes<TVocabulary, TGuards, TRefusalsOpt, TGuardsOpt> = (LambderRefusalNamesIn<TRefusalsOpt> | LambderGuardRefusalNamesOf<TGuards, TGuardsOpt>) & keyof TVocabulary & string;
+/**
+ * What an endpoint's handler is handed: the session context when one of its
+ * guards needs a session (so ctx.session is typed present), the plain one
+ * otherwise, with the payload, the guards' data and a refuse() typed to the
+ * codes the endpoint may refuse with.
+ */
+export type LambderApiHandlerContext<TApp extends LambderAppTypes, TPayload, TGuardsOpt, TRefusalsOpt> = (LambderApiModeOf<TApp["guards"], TGuardsOpt> extends "session" ? LambderSessionRenderContext<TPayload, TApp["session"], Record<string, string>, LambderGuardDataOf<TApp["guards"], TGuardsOpt>, TApp["policies"]> : LambderRenderContext<TPayload, Record<string, string>, LambderGuardDataOf<TApp["guards"], TGuardsOpt>, TApp["session"], TApp["policies"]>) & {
+    refuse: LambderDeclaredRefuse<LambderHandlerRefusalsOf<TApp["refusals"], LambderApiRefusalCodes<TApp["refusals"], TApp["guards"], TRefusalsOpt, TGuardsOpt>>, TApp["refusalCodesRequired"]>;
+};
+/**
+ * Declares one endpoint, typed on one set of app types: its input and output
+ * schemas, its guards, rate limits, idempotency and refusals, and its
+ * handler. Nothing is registered until the declaration is put in a group
+ * (defineApiGroup) and the group is registered (registerApiGroups).
+ *
+ * The guards say who may call it, and so its mode: an endpoint whose guards
+ * include one that needs a session (`session: true`) is a session endpoint,
+ * its session read before the guards run and a call without one answered
+ * sessionExpired, and its handler's ctx.session is typed present. Any other
+ * endpoint is public.
+ */
+export type LambderDefineApi<TApp extends LambderAppTypes> = <TInput extends z.ZodType, TOutput extends z.ZodType, const TAnswer extends LambderReadonlyDeep<z.input<TOutput>>, const TRateOpt extends LambderRateLimitOption<TApp["policies"]> = never, const TGuardsOpt extends LambderGuardsOption<TApp["guards"]> = never, const TIdempotencyOpt extends LambderApiIdempotencyOption = never, const TRefusalsOpt extends LambderRefusalsOption<TApp["refusals"]> = never>(options: {
+    input: TInput;
+    output: TOutput;
+} & {
+    /** Named rate limits, checked in declared order within their phase (per ip before the session read, per session before the guards, a custom key after the guards and input validation): a name, a list of names, or a { name: true | override } map (windows overridable on perApi budgets, refusal on any). The first exceeded one refuses (429 envelope + Retry-After); attempts count on every counter checked before it. A per-session policy needs one of the endpoint's guards to need a session. */
+    rateLimit?: TRateOpt;
+    /** Replay-protect this API per client idempotencyKey. Requires the idempotency option at creation. */
+    idempotency?: TApp["idempotency"] extends true ? TIdempotencyOpt : never;
+    /**
+     * The refusal codes this API may refuse with, from the vocabulary given at creation: one code or a
+     * non-empty list. Its guards' codes join them. The handler raises one with `ctx.refuse(content, { code, data })`,
+     * its callers narrow on them, and a refusal with any other code is a crash rather than an answer.
+     */
+    refusals?: TRefusalsOpt;
+    /**
+     * Whether this API's answers are compressed for a caller that accepts it: "auto" (the default) when the
+     * body is large enough to gain, false never, true always. false suits an answer of base64 bytes: once
+     * compressed it leaves the function base64-encoded again, so it is no smaller under Lambda's response
+     * cap or to a lambda caller, and a browser gets it only about a quarter smaller for the time spent at
+     * both ends. A transport setting of this server's, not part of the API's contract.
+     */
+    compress?: boolean | "auto";
+} & LambderRequirableGuardsField<TApp["guardsRequired"], TGuardsOpt> & LambderObjectOutputCheck<TOutput> & LambderPayloadSliceCheck<TApp["guards"], TApp["policies"], TGuardsOpt, TRateOpt, z.input<TInput>> & LambderPublicSessionPolicyCheck<LambderApiModeOf<TApp["guards"], TGuardsOpt>, TApp["policies"], TRateOpt> & LambderSessionModeCheck<LambderApiModeOf<TApp["guards"], TGuardsOpt>, TApp["sessions"]>, 
+/** Answers the call by returning its output (parsed through `output` before it is sent), or refuses it with ctx.refuse() or refuse(). */
+handler: (ctx: LambderApiHandlerContext<TApp, z.infer<TInput>, TGuardsOpt, TRefusalsOpt>) => LambderMaybePromise<TAnswer>) => LambderApiDeclaration<LambderContractEntry<z.input<TInput>, LambderJsonOf<z.output<TOutput>>, LambderApiModeOf<TApp["guards"], TGuardsOpt>, LambderGuardInputsOf<TApp["guards"], TGuardsOpt>, TGuardsOpt, TRateOpt, TIdempotencyOpt, LambderWireRefusalsOf<TApp["refusals"], LambderApiRefusalCodes<TApp["refusals"], TApp["guards"], TRefusalsOpt, TGuardsOpt>>>>;
+/**
+ * Gathers endpoints into a named group: each is registered as `name.action`
+ * and called at `{apiPath}/{name}/{action}`, and every Lambder caller
+ * reaches it as `caller.name.action(input)`. A group's name and its actions
+ * are identifiers, and a group may not take a name a caller already answers
+ * for (see LAMBDER_RESERVED_GROUP_NAMES).
+ *
+ * A group declared across files takes each file's part:
+ * `defineApiGroup("orders", orderReadApis, orderWriteApis)`. An action two
+ * parts declare is refused, at compile time and at startup, rather than one
+ * silently replacing the other as an object spread would. Endpoints a
+ * module's builders declared may sit in any group: registering it adds
+ * their module.
+ */
+export type LambderDefineApiGroup = <const TName extends string, const TParts extends readonly [LambderApiDeclarations, ...LambderApiDeclarations[]]>(name: TName & LambderGroupNameCheck<TName>, ...parts: TParts & LambderGroupPartsCheck<TParts> & {
+    [TIndex in keyof TParts]: LambderActionNamesCheck<TParts[TIndex]>;
+}) => LambderApiGroup<TName, LambderMergedParts<TParts>>;
+/**
+ * A group loaded on the first call to one of its endpoints:
+ * `lazyApiGroup("orders", () => import("./orders.js").then((m) => m.orderApis))`.
+ * A cold start then parses none of it, nor anything only it imports, until
+ * a request calls it; the contract is the loaded group's, read off its type.
+ * The group loaded must carry the same name, which the type checks and
+ * loading checks again. `loadApiGroups()` loads every group, for a build
+ * step or a boot check that has to see them all.
+ *
+ * A module's lazyApiGroup carries the module, so its guards and policies
+ * are added when the group is registered, at startup, rather than when it
+ * loads; a group whose endpoints a module's builders declared is registered
+ * lazily with that module's.
+ */
+export type LambderDefineLazyApiGroup = <const TName extends string, TGroup extends LambderApiGroup<TName, any>>(name: TName & LambderGroupNameCheck<TName>, load: () => Promise<TGroup>) => LambderLazyApiGroup<TName, NoInfer<TGroup>>;
+/** The three builders, typed on one set of app types. */
+export type LambderApiBuilders<TApp extends LambderAppTypes> = {
+    readonly defineApi: LambderDefineApi<TApp>;
+    readonly defineApiGroup: LambderDefineApiGroup;
+    readonly lazyApiGroup: LambderDefineLazyApiGroup;
+};
+/**
+ * The builders as values: the instance's own (module null), or a module's,
+ * whose endpoints and lazy groups carry the module for registration to add.
+ * Plain functions closing over nothing else, so an app may hand them out
+ * detached.
+ */
+export declare const apiBuildersFor: <TApp extends LambderAppTypes>(module: LambderApiModuleDeclarations | null) => LambderApiBuilders<TApp>;

package/dist/core/LambderApiBuilders.js

@@ -0,0 +1,12 @@
+import { buildApiGroup, buildLazyApiGroup, } from "../api/LambderApiDeclarations.js";
+/**
+ * The builders as values: the instance's own (module null), or a module's,
+ * whose endpoints and lazy groups carry the module for registration to add.
+ * Plain functions closing over nothing else, so an app may hand them out
+ * detached.
+ */
+export const apiBuildersFor = (module) => ({
+    defineApi: ((options, handler) => module ? { kind: "lambderApi", options, handler, module } : { kind: "lambderApi", options, handler }),
+    defineApiGroup: ((name, ...parts) => buildApiGroup(name, parts)),
+    lazyApiGroup: ((name, load) => buildLazyApiGroup(name, load, module)),
+});