lambder 15.0.2 → 16.0.1

package/CHANGELOG.md

@@ -9,6 +9,124 @@ 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.
 
+## [16.0.1] - 2026-11-08
+
+A major. Modules: guards and rate-limit policies a part of an app declares
+for its own endpoints, so the file creating an instance imports no part's;
+the types an app's declaration files need, exported; and a mock's guards held
+at the entry rather than at `create()`. Every break is named under Changed.
+
+### Added
+
+- **`defineApiModule({ guards, rateLimitPolicies })`** on an instance, and
+  `LambderApiModule`, what it returns: `defineApi`, `defineApiGroup` and
+  `lazyApiGroup` typed on the instance's guards and policies with the
+  module's beside them, so a module's endpoints name either and an unknown
+  name is still a compile error, while the instance's own builders, and every
+  other module's, see none of the module's names. Registering a group adds
+  the modules its endpoints were declared with to the instance; a module's
+  `lazyApiGroup` carries the module, so its group adds it at registration,
+  before it loads, and `apiOptionEntries()`, `apiSignatures()`, the
+  generated tables and a route charging one of its policies all see it from
+  the start. A module reaches an instance only through its groups: on an
+  instance that registers none of them, a route charging one of its policies
+  fails at its first request. Each option takes one map or a list of maps,
+  held to what `create()` holds its own to. A name the instance declares is
+  refused where the module is defined, at compile time and at the call; a
+  name two modules declare is refused when the second is registered, and the
+  refused registration leaves the instance as it was. A module declaring
+  policies needs the instance's limiter. A lazy group registered with the
+  instance's own `lazyApiGroup` whose loaded endpoints a module declared is
+  refused when it loads. `LambderRenderContextOf<typeof module>` types a
+  helper handed one of its handlers' contexts.
+- **`defineApiModule({ guards })` on a mock app**, and `LambderMockApiModule`:
+  `api`, `notMocked`, `apiSlice` and `override` with a module's mock guards
+  beside the app's, added when its entries are registered, each guard held to
+  the contract and the generated `guardDeclarations` as `create()`'s are, and
+  the same rule for names. A mock module takes no policies: the mock takes
+  them all at `create()`, from the generated table.
+- **`rateLimits: { limiter }` with no policies**, for an instance whose
+  policies are all its modules'. An empty `policies: {}` is still refused.
+- **The types an app's declaration files name are exported**, so an app that
+  emits declaration files (`declaration`, `composite`) no longer stops at
+  TS2883 ("cannot be named without a reference to ... from lambder"). The
+  builders are named types, `LambderDefineApi`, `LambderDefineApiGroup` and
+  `LambderDefineLazyApiGroup`, so a builder handed out destructured or under
+  the instance's name is declared by that name. Exported with them: the
+  fourteen names seen missing on an app's own declarations
+  (`LambderObjectOutputCheck`, `LambderPolicyPerOf`,
+  `LambderPublicSessionPolicyCheck`, `LambderSessionModeCheck`,
+  `LambderMaybePromise`, which was `MaybePromise` and unexported,
+  `LambderActionNamesCheck`, `LambderGroupNameCheck`,
+  `LambderGroupPartsCheck`, `LambderMergedParts`, `LambderGivenOption`,
+  `LambderInitCreateOptions`, `LambderMergedNamedMaps`,
+  `LambderNamedMapsOption`, `LambderNestedOptionChecks`);
+  `LambderRefusalVocabularyOptionChecks`, from both entries; the module types;
+  and the types written directly into a builder's, a method's or a
+  constructor's parameters (`LambderPayloadSliceCheck`,
+  `LambderRequirableGuardsField`, `LambderSessionEnabledInstance`,
+  `LambderRegisteredGroupsCheck`, `LambderNoExtraKeys`,
+  `LambderApiHandlerContext`, `LambderApiModuleOptions`,
+  `LambderApiModuleOptionChecks`, `LambderApiModuleDeclarations`, and on the
+  mock entry `LambderMockApiModuleOptions`, `LambderMockApiModuleChecks`,
+  `LambderMockApiModuleDoor`, `LambderMockEntryGuardsCheck` and
+  `LambderMockNotMockedGuardsCheck`). A test emits the declarations of a
+  sample app against the built package and fails on any diagnostic: a server
+  (an exported init, create() in a factory, the builders destructured and
+  under the instance's name, groups, lazy groups, a module, a list of parts,
+  the entry, routes, a test app, an invoke caller) and a mock (the vocabulary
+  declared, the generated tables given to create(), entries as handlers,
+  `notMocked`, a mock module, `register()`). The other names are kept for the
+  shapes the sample does not reach.
+
+### Changed
+
+- **A mock's guards are held at the entry rather than at `create()`.** The
+  `guards` option need no longer name every guard the contract declares,
+  since a module may declare its own; each entry instead needs a mock guard
+  for every guard its endpoint declares in the map it is built with, and,
+  without the `apiOptions` table, a session endpoint's entry needs one
+  declared `session: true`. Both are compile errors on the entry's name. A
+  guard the map does name is still held to the contract.
+  `LambderMockSessionGuardsCheck` is removed, replaced by
+  `LambderMockEntryGuardsCheck` (and `LambderMockNotMockedGuardsCheck` for
+  `notMocked`). A `@ts-expect-error` on a `create()` that leaves out a guard
+  the contract declares is now unused (TS2578): the error is at the entry.
+- **`api()` and `notMocked()` take their name as
+  `K & LambderMockEntryGuardsCheck<...>` and
+  `K & LambderMockNotMockedGuardsCheck<...>`.** A wrapper generic over the
+  endpoint name that passes its own type parameter on no longer compiles
+  (TS2345); call them with a concrete name, or cast the name in the wrapper.
+- **`LambderApiRateLimitsConfig.policies` is optional**, matching the
+  `rateLimits` option above, so code reading `.policies` off one sees
+  `| undefined`.
+
+## [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/api/LambderApiDeclarations.d.ts

@@ -1,9 +1,10 @@
 import type { z } from "zod";
-import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderMaybePromise } from "../shared/util/LambderTypeUtilities.js";
 import type { LambderApiMode, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue, LambderRefusalsOptionValue } from "../shared/wire/LambderApiOptionValues.js";
 import type { LambderApiRateLimitPolicyConfig, LambderPolicyPerOf } from "./LambderApiRateLimits.js";
 import type { LambderRefusalVocabulary } from "./LambderApiRefusals.js";
+import type { LambderApiModuleDeclarations, LambderApiModuleUse } from "./LambderApiModules.js";
 import { type LambderReservedActionName, type LambderReservedGroupName } from "../shared/wire/LambderApiNames.js";
 /**
  * What an instance's declarations are typed against, fixed at create(): the
@@ -83,12 +84,14 @@ declare const LAMBDER_CONTRACT_ENTRY: unique symbol;
 /**
  * One endpoint, declared: its options and its handler, and in its type the
  * contract entry a client calls it by. Built by an instance's defineApi(),
- * registered by being put in a group.
+ * or a module's, registered by being put in a group.
  */
 export type LambderApiDeclaration<TEntry = unknown> = {
     readonly kind: "lambderApi";
     readonly options: LambderApiDeclarationOptions;
-    readonly handler: (ctx: never) => MaybePromise<unknown>;
+    readonly handler: (ctx: never) => LambderMaybePromise<unknown>;
+    /** The module whose builders declared it (defineApiModule), whose guards and policies its group's registration adds; absent on the instance's own. */
+    readonly module?: LambderApiModuleDeclarations;
     readonly [LAMBDER_CONTRACT_ENTRY]: TEntry;
 };
 /** A group's endpoints by action name. */
@@ -108,6 +111,12 @@ export type LambderLazyApiGroup<TName extends string = string, TGroup extends La
     readonly kind: "lambderLazyApiGroup";
     readonly name: TName;
     readonly load: () => Promise<TGroup>;
+    /**
+     * The module whose lazyApiGroup registered it, whose guards and policies
+     * its registration adds at once, before the group loads; absent on the
+     * instance's own.
+     */
+    readonly module?: LambderApiModuleDeclarations;
 };
 /** Either kind of group registerApiGroups() takes. */
 export type LambderRegistrableApiGroup = LambderApiGroup<string, any> | LambderLazyApiGroup<string, any>;
@@ -193,8 +202,15 @@ export type LambderActionNamesCheck<TApis> = [
  * usually one part; one declared across files gives each file's part.
  */
 export declare const buildApiGroup: <TName extends string, TApis extends LambderApiDeclarations>(name: TName, parts: readonly LambderApiDeclarations[]) => LambderApiGroup<TName, TApis>;
-/** Builds a lazy group; the name is checked here, the group it loads when it loads. */
-export declare const buildLazyApiGroup: <TName extends string, TGroup extends LambderApiGroup<TName, any>>(name: TName, load: () => Promise<TGroup>) => LambderLazyApiGroup<TName, TGroup>;
+/** Builds a lazy group, carrying the module that registers it, if one does; the name is checked here, the group it loads when it loads. */
+export declare const buildLazyApiGroup: <TName extends string, TGroup extends LambderApiGroup<TName, any>>(name: TName, load: () => Promise<TGroup>, module: LambderApiModuleDeclarations | null) => LambderLazyApiGroup<TName, TGroup>;
+/**
+ * The modules a group brings to its registration, each with where it was
+ * met: a lazy group's own (the module whose lazyApiGroup registered it), and
+ * a group's endpoints' (the modules whose builders declared them), each
+ * module once.
+ */
+export declare const apiModuleUsesOf: (group: LambderRegistrableApiGroup) => LambderApiModuleUse[];
 /** Whether a value is either kind of group registerApiGroups() takes. */
 export declare const isRegistrableApiGroup: (value: unknown) => value is LambderRegistrableApiGroup;
 export {};

package/dist/api/LambderApiDeclarations.js

@@ -36,14 +36,32 @@ export const buildApiGroup = (name, parts) => {
     }
     return { kind: "lambderApiGroup", name, apis: apis };
 };
-/** Builds a lazy group; the name is checked here, the group it loads when it loads. */
-export const buildLazyApiGroup = (name, load) => {
+/** Builds a lazy group, carrying the module that registers it, if one does; the name is checked here, the group it loads when it loads. */
+export const buildLazyApiGroup = (name, load, module) => {
     if (typeof name !== "string" || !isGroupName(name)) {
         throw new Error(`Lambder: ${describeName(name)} cannot name a group. A group is a letter then letters, digits or underscores, and not a name a caller already answers for.`);
     }
     if (typeof load !== "function")
         throw new Error(`Lambder: lazy group "${name}" has no loader. Pass a function that imports the group: () => import("./orders.js").then((m) => m.orderApis).`);
-    return { kind: "lambderLazyApiGroup", name, load };
+    return module ? { kind: "lambderLazyApiGroup", name, load, module } : { kind: "lambderLazyApiGroup", name, load };
+};
+/**
+ * The modules a group brings to its registration, each with where it was
+ * met: a lazy group's own (the module whose lazyApiGroup registered it), and
+ * a group's endpoints' (the modules whose builders declared them), each
+ * module once.
+ */
+export const apiModuleUsesOf = (group) => {
+    if (group.kind === "lambderLazyApiGroup") {
+        return group.module ? [{ module: group.module, usedBy: `registering lazy group "${group.name}"` }] : [];
+    }
+    const uses = [];
+    for (const [action, declaration] of Object.entries(group.apis)) {
+        const module = declaration.module;
+        if (module && !uses.some((use) => use.module === module))
+            uses.push({ module, usedBy: `declaring "${group.name}.${action}"` });
+    }
+    return uses;
 };
 /** Whether a value is either kind of group registerApiGroups() takes. */
 export const isRegistrableApiGroup = (value) => {

package/dist/api/LambderApiGuards.d.ts

@@ -390,6 +390,14 @@ export declare const toGuardEntries: (value?: LambderGuardsOptionValue) => {
     name: string;
     param: unknown;
 }[];
+/**
+ * Refuses a guard that cannot run: no handler, both input modes, a refusals
+ * option that is not a list of codes, an unknown runAt, a singleUseInput
+ * that is not a boolean or sits on a guard without a guardInput. What the
+ * guards option at creation and a module's guards (defineApiModule) are each
+ * held to, one rule for both.
+ */
+export declare const assertGuardDeclaration: (name: string, guardDef: LambderApiGuard<any, any, any>) => void;
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared
@@ -399,12 +407,24 @@ export declare const toGuardEntries: (value?: LambderGuardsOptionValue) => {
  */
 export declare class LambderApiGuardsEngine {
     private guards;
-    /** True once a guards map was configured. */
+    /** True once a guards map was configured, or a module added guards. */
     get isConfigured(): boolean;
+    /** Whether a guard of this name is declared, by the creation's map or a module added since. */
+    has(name: string): boolean;
     /** Take the guards map given at creation; named like the other two engines' configure(). */
     configure(guards: Record<string, LambderApiGuard<any, any, any>>): void;
-    /** Startup validation of one API registration's guards option. */
-    assertRegistration(apiName: string, mode: LambderApiMode, guardsOption?: LambderGuardsOptionValue): void;
+    /**
+     * Adds a module's guards beside the ones declared so far. Its names were
+     * checked against them before (LambderApiPipeline.modulesToAdd), so a
+     * name met again here is a caller that skipped that check.
+     */
+    add(guards: Readonly<Record<string, LambderApiGuard<any, any, any>>>): void;
+    /**
+     * Startup validation of one API registration's guards option. `adding`
+     * holds the guards of the modules the same registration adds, which the
+     * engine takes only once every endpoint of it passed.
+     */
+    assertRegistration(apiName: string, mode: LambderApiMode, guardsOption?: LambderGuardsOptionValue, adding?: Readonly<Record<string, LambderApiGuard<any, any, any>>>): void;
     /**
      * The posted guard inputs an idempotency fingerprint holds for an API
      * declaring `guardsOption`: the value of each of its `guardInput` guards

package/dist/api/LambderApiGuards.js

@@ -35,6 +35,34 @@ export const toGuardEntries = (value) => {
  * unrestricted, so the read has to handle this.
  */
 const readGuardInput = (guardInputs, name) => guardInputs !== undefined && Object.prototype.hasOwnProperty.call(guardInputs, name) ? guardInputs[name] : undefined;
+/**
+ * Refuses a guard that cannot run: no handler, both input modes, a refusals
+ * option that is not a list of codes, an unknown runAt, a singleUseInput
+ * that is not a boolean or sits on a guard without a guardInput. What the
+ * guards option at creation and a module's guards (defineApiModule) are each
+ * held to, one rule for both.
+ */
+export const assertGuardDeclaration = (name, guardDef) => {
+    if (typeof guardDef?.handler !== "function")
+        throw new Error(`Lambder: guard "${name}" has no handler function.`);
+    if (guardDef.apiInput && guardDef.guardInput)
+        throw new Error(`Lambder: guard "${name}" declares both apiInput and guardInput; pick one.`);
+    const refusals = guardDef.refusals;
+    if (refusals !== undefined && (!Array.isArray(refusals) || refusals.some((code) => typeof code !== "string" || code === ""))) {
+        throw new Error(`Lambder: guard "${name}" has a refusals option that is not a list of refusal codes.`);
+    }
+    const runAt = guardDef.runAt;
+    if (runAt !== undefined && runAt !== "beforeInputValidation" && runAt !== "afterInputValidation") {
+        throw new Error(`Lambder: guard "${name}" has runAt "${String(runAt)}"; use "beforeInputValidation" (default) or "afterInputValidation".`);
+    }
+    const singleUseInput = guardDef.singleUseInput;
+    if (singleUseInput !== undefined && typeof singleUseInput !== "boolean") {
+        throw new Error(`Lambder: guard "${name}" has singleUseInput ${String(singleUseInput)}; write true for a value a retry carries fresh, or leave it off.`);
+    }
+    if (singleUseInput && !guardDef.guardInput) {
+        throw new Error(`Lambder: guard "${name}" declares singleUseInput without a guardInput. Only a value the client sends beside the payload can be left out of an idempotent request's fingerprint; a slice of the payload always counts.`);
+    }
+};
 /**
  * Runtime side of the guards subsystem: holds the defined guards, asserts
  * API registrations against them at startup, and executes an API's declared
@@ -49,8 +77,10 @@ export class LambderApiGuardsEngine {
     // that typo and then fail on every request. It would also refuse to
     // register a guard legitimately named one of them.
     guards = new Map();
-    /** True once a guards map was configured. */
+    /** True once a guards map was configured, or a module added guards. */
     get isConfigured() { return this.guards.size > 0; }
+    /** Whether a guard of this name is declared, by the creation's map or a module added since. */
+    has(name) { return this.guards.has(name); }
     /** Take the guards map given at creation; named like the other two engines' configure(). */
     configure(guards) {
         // One configuration per instance, as in the rate-limit and idempotency
@@ -65,33 +95,28 @@ export class LambderApiGuardsEngine {
         if (Object.keys(guards).length === 0) {
             throw new Error("Lambder: the guards option was declared with no guards in it, which configures nothing. Name the guards APIs will declare, or leave the option off.");
         }
+        this.add(guards);
+    }
+    /**
+     * Adds a module's guards beside the ones declared so far. Its names were
+     * checked against them before (LambderApiPipeline.modulesToAdd), so a
+     * name met again here is a caller that skipped that check.
+     */
+    add(guards) {
         for (const [name, guardDef] of Object.entries(guards)) {
             if (this.guards.has(name))
                 throw new Error(`Lambder: guard "${name}" is already defined.`);
-            if (typeof guardDef?.handler !== "function")
-                throw new Error(`Lambder: guard "${name}" has no handler function.`);
-            if (guardDef.apiInput && guardDef.guardInput)
-                throw new Error(`Lambder: guard "${name}" declares both apiInput and guardInput; pick one.`);
-            const refusals = guardDef.refusals;
-            if (refusals !== undefined && (!Array.isArray(refusals) || refusals.some((code) => typeof code !== "string" || code === ""))) {
-                throw new Error(`Lambder: guard "${name}" has a refusals option that is not a list of refusal codes.`);
-            }
-            const runAt = guardDef.runAt;
-            if (runAt !== undefined && runAt !== "beforeInputValidation" && runAt !== "afterInputValidation") {
-                throw new Error(`Lambder: guard "${name}" has runAt "${String(runAt)}"; use "beforeInputValidation" (default) or "afterInputValidation".`);
-            }
-            const singleUseInput = guardDef.singleUseInput;
-            if (singleUseInput !== undefined && typeof singleUseInput !== "boolean") {
-                throw new Error(`Lambder: guard "${name}" has singleUseInput ${String(singleUseInput)}; write true for a value a retry carries fresh, or leave it off.`);
-            }
-            if (singleUseInput && !guardDef.guardInput) {
-                throw new Error(`Lambder: guard "${name}" declares singleUseInput without a guardInput. Only a value the client sends beside the payload can be left out of an idempotent request's fingerprint; a slice of the payload always counts.`);
-            }
-            this.guards.set(name, guardDef);
+            assertGuardDeclaration(name, guardDef);
         }
+        for (const [name, guardDef] of Object.entries(guards))
+            this.guards.set(name, guardDef);
     }
-    /** Startup validation of one API registration's guards option. */
-    assertRegistration(apiName, mode, guardsOption) {
+    /**
+     * Startup validation of one API registration's guards option. `adding`
+     * holds the guards of the modules the same registration adds, which the
+     * engine takes only once every endpoint of it passed.
+     */
+    assertRegistration(apiName, mode, guardsOption, adding) {
         const entries = toGuardEntries(guardsOption);
         // The runtime half of LambderNonEmptyOptionMap on the guards option.
         // `guards: {}` and `guards: []` would satisfy the require*ApiGuards
@@ -103,9 +128,9 @@ export class LambderApiGuardsEngine {
                 `Name the guard that authorizes it, or omit the option entirely.`);
         }
         for (const { name } of entries) {
-            const guardDef = this.guards.get(name);
+            const guardDef = this.guards.get(name) ?? (adding && Object.prototype.hasOwnProperty.call(adding, name) ? adding[name] : undefined);
             if (!guardDef) {
-                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation.`);
+                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Declare it in the guards option at creation, or in the module the API is declared with (defineApiModule).`);
             }
             if (guardDef.session && mode !== "session") {
                 throw new Error(`Lambder: API "${apiName}" uses guard "${name}" (session: true) but is registered as public. An endpoint declaring a session guard is a session endpoint.`);

package/dist/api/LambderApiModules.d.ts

@@ -0,0 +1,50 @@
+import { type LambderApiGuard } from "./LambderApiGuards.js";
+import { type LambderApiRateLimitPolicyConfig } from "./LambderApiRateLimits.js";
+import { type LambderNamedMapsOption } from "../shared/util/LambderNamedMaps.js";
+/** One map of guards, of either adapter's contexts. */
+type LambderModuleGuards = Readonly<Record<string, LambderApiGuard<any, any, any, any, any>>>;
+/** One map of rate-limit policies, of either adapter's contexts. */
+type LambderModulePolicies = Readonly<Record<string, LambderApiRateLimitPolicyConfig<any>>>;
+/**
+ * What a module declares, as registration adds it: its guards and its
+ * rate-limit policies, merged into one map each. One object per module, made
+ * once by defineApiModule() and carried by every endpoint its builders
+ * declare and every lazy group its lazyApiGroup registers: the object is how
+ * a registration finds a module and tells two apart.
+ */
+export type LambderApiModuleDeclarations = {
+    readonly guards: LambderModuleGuards;
+    readonly rateLimitPolicies: LambderModulePolicies;
+};
+/** A module a registration brings, and where it was met, for the error naming a name two declare. */
+export type LambderApiModuleUse = {
+    readonly module: LambderApiModuleDeclarations;
+    /** How the error names the module: "declaring group \"orders\"", say. */
+    readonly usedBy: string;
+};
+/**
+ * The modules one registration adds, checked against what the instance
+ * declares and against each other, their declarations merged. Registration
+ * checks every endpoint against these and the instance's own before the
+ * pipeline takes them (LambderApiPipeline.addModules), so a refused
+ * registration leaves the instance as it was.
+ */
+export type LambderAddedApiModules = {
+    readonly modules: readonly LambderApiModuleDeclarations[];
+    readonly guards: LambderModuleGuards;
+    readonly rateLimitPolicies: LambderModulePolicies;
+};
+/** What a registration checks an endpoint's names against beside the instance's own: the declarations of the modules it is adding, or of the one module building an entry. */
+export type LambderPendingDeclarations = Pick<LambderAddedApiModules, "guards" | "rateLimitPolicies">;
+/**
+ * A module's declarations from what defineApiModule() was given: each option
+ * one map or a list of them, merged, a name two of a list's maps declare
+ * refused; every guard and policy held to the rules the creation's are held
+ * to. A module declaring nothing is refused, as an empty guards option is:
+ * its builders would be the instance's own.
+ */
+export declare const apiModuleDeclarationsOf: (options: {
+    guards?: LambderNamedMapsOption<LambderModuleGuards>;
+    rateLimitPolicies?: LambderNamedMapsOption<LambderModulePolicies>;
+}, owner: "Lambder" | "LambderMockApp") => LambderApiModuleDeclarations;
+export {};

package/dist/api/LambderApiModules.js

@@ -0,0 +1,36 @@
+import { assertGuardDeclaration } from "./LambderApiGuards.js";
+import { assertRateLimitPolicyDeclaration } from "./LambderApiRateLimits.js";
+import { mergeNamedMaps } from "../shared/util/LambderNamedMaps.js";
+/** A record with no prototype, so a declaration named "__proto__" or "constructor" is a key like any other. */
+const bareRecord = () => Object.create(null);
+/**
+ * A module's declarations from what defineApiModule() was given: each option
+ * one map or a list of them, merged, a name two of a list's maps declare
+ * refused; every guard and policy held to the rules the creation's are held
+ * to. A module declaring nothing is refused, as an empty guards option is:
+ * its builders would be the instance's own.
+ */
+export const apiModuleDeclarationsOf = (options, owner) => {
+    const guards = bareRecord();
+    const rateLimitPolicies = bareRecord();
+    if (options.guards !== undefined) {
+        for (const [name, guard] of Object.entries(mergeNamedMaps(options.guards, "guard", "defineApiModule()"))) {
+            assertGuardDeclaration(name, guard);
+            guards[name] = guard;
+        }
+    }
+    if (options.rateLimitPolicies !== undefined) {
+        for (const [name, policy] of Object.entries(mergeNamedMaps(options.rateLimitPolicies, "rate-limit policy", "defineApiModule()"))) {
+            assertRateLimitPolicyDeclaration(name, policy);
+            rateLimitPolicies[name] = policy;
+        }
+    }
+    if (Object.keys(guards).length === 0 && Object.keys(rateLimitPolicies).length === 0) {
+        throw new Error(owner === "Lambder"
+            ? "Lambder: defineApiModule() was given no guard and no rate-limit policy, which declares nothing a module's endpoints could name " +
+                "beyond the instance's own. Declare the module's guards or rate-limit policies, or declare its endpoints with the instance's builders."
+            : "LambderMockApp: defineApiModule() was given no guard, which declares nothing a module's entries could name beyond the app's own. " +
+                "Declare the module's mock guards, or build its entries with the app's own builders.");
+    }
+    return Object.freeze({ guards: Object.freeze(guards), rateLimitPolicies: Object.freeze(rateLimitPolicies) });
+};

package/dist/api/LambderApiPipeline.d.ts

@@ -10,13 +10,14 @@ import { type LambderEndpointRefusals } from "./LambderApiRefusals.js";
 import { type LambderApiGuard } from "./LambderApiGuards.js";
 import { type LambderApiRateLimitPolicyConfig, type LambderApiRateLimitsConfig, type LambderRateLimitChargeResult, type LambderRateLimitChargeSubject } from "./LambderApiRateLimits.js";
 import { type LambderApiIdempotencyConfig } from "./LambderApiIdempotency.js";
+import type { LambderAddedApiModules, LambderApiModuleDeclarations, LambderApiModuleUse, LambderPendingDeclarations } from "./LambderApiModules.js";
 import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
 import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
 import type LambderSessionManager from "../session/LambderSessionManager.js";
 import LambderSessionController, { type LambderSessionCookieOptions, type LambderSessionRequestInfo } from "../session/LambderSessionController.js";
-import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderMaybePromise } from "../shared/util/LambderTypeUtilities.js";
 /**
  * The app's own answer for a rejected input (setApiInputValidationErrorHandler
  * on the server). Returning null asks for the standard 422 body, which only
@@ -24,7 +25,7 @@ import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
  * API's schema and every preflight slice (guard inputs, rate-limit keys)
  * answer through here, so one failure has one shape.
  */
-export type LambderApiInputRefusal<TCtx> = (zodError: z.ZodError, ctx: TCtx, request: LambderApiRequest) => MaybePromise<LambderApiAnswer | null>;
+export type LambderApiInputRefusal<TCtx> = (zodError: z.ZodError, ctx: TCtx, request: LambderApiRequest) => LambderMaybePromise<LambderApiAnswer | null>;
 /** The session subsystem as the pipeline runs it: the manager plus the cookie names and scope the controller writes. */
 export type LambderApiSessionsConfig<TSessionData> = {
     manager: LambderSessionManager<TSessionData>;
@@ -140,6 +141,8 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
     private readonly onInvalidInput;
     private readonly sessions;
     private readonly apiSignatures;
+    /** The modules whose guards and rate-limit policies this pipeline took (addModules), each once. */
+    private readonly modules;
     constructor(options?: LambderApiPipelineOptions<TCtx, TSessionData>);
     /** True when a session manager was configured. */
     get hasSessions(): boolean;
@@ -165,8 +168,28 @@ export declare class LambderApiPipeline<TCtx extends LambderApiCallContext<TSess
      * being counted, since only it knows whether the request is an API call.
      */
     chargeRateLimit(name: string, subject: LambderRateLimitChargeSubject): Promise<LambderRateLimitChargeResult>;
-    /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */
-    assertRegistration(definition: LambderApiDefinition): void;
+    /** Whether this pipeline took the module's guards and rate-limit policies already. */
+    hasModule(module: LambderApiModuleDeclarations): boolean;
+    /**
+     * The modules among `uses` this pipeline has not taken yet, checked and
+     * merged, and nothing taken: a name one of them declares that this
+     * pipeline declares already (at creation, or by a module taken before)
+     * or that another of them declares is refused, as create() refuses a name
+     * two maps declare, and so are rate-limit policies on a pipeline with no
+     * limiter for them. A module met twice is one module. addModules() takes
+     * what this returns once every endpoint of the registration passed.
+     */
+    modulesToAdd(uses: readonly LambderApiModuleUse[]): LambderAddedApiModules;
+    /** Takes the guards and rate-limit policies of the modules modulesToAdd() checked: from here on its endpoints run them, and code may charge the policies. */
+    addModules(added: LambderAddedApiModules): void;
+    /**
+     * Registration-time checks of one definition's declarative options; the
+     * same messages on the server and in the mock. `adding` holds the guards
+     * and policies a registration is about to add beside this pipeline's own:
+     * those of the modules it brings (modulesToAdd), or of the module an
+     * entry is built with.
+     */
+    assertRegistration(definition: LambderApiDefinition, adding?: LambderPendingDeclarations): void;
     /**
      * The answer for a request naming no registered API: the apiNotFound
      * refusal, carrying whatever the call already wrote (a CORS header, a