lambder 15.0.2 → 16.0.1

package/dist/api/LambderApiPipeline.js

@@ -60,6 +60,8 @@ export class LambderApiPipeline {
     onInvalidInput;
     sessions;
     apiSignatures;
+    /** The modules whose guards and rate-limit policies this pipeline took (addModules), each once. */
+    modules = new Set();
     constructor(options = {}) {
         this.apiVersion = options.apiVersion ?? null;
         // Dotted, always, whether or not a floor is set today: the floor reads
@@ -160,19 +162,83 @@ export class LambderApiPipeline {
     async chargeRateLimit(name, subject) {
         return await this.rateLimits.chargePolicy(name, subject);
     }
-    /** Registration-time checks of one definition's declarative options; the same messages on the server and in the mock. */
-    assertRegistration(definition) {
+    /** Whether this pipeline took the module's guards and rate-limit policies already. */
+    hasModule(module) {
+        return this.modules.has(module);
+    }
+    /**
+     * 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) {
+        const modules = [];
+        const guards = Object.create(null);
+        const rateLimitPolicies = Object.create(null);
+        const guardModules = new Map();
+        const policyModules = new Map();
+        const claim = (what, name, usedBy, declaredHere, claimed) => {
+            if (declaredHere) {
+                throw new Error(`Lambder: the ${what} "${name}" of the module ${usedBy} is declared already, at creation or by a module registered before. ` +
+                    `A module declares names of its own: rename one of the two.`);
+            }
+            const other = claimed.get(name);
+            if (other !== undefined) {
+                throw new Error(`Lambder: the ${what} "${name}" is declared by two modules, the one ${other} and the one ${usedBy}. Declare each name once.`);
+            }
+            claimed.set(name, usedBy);
+        };
+        for (const { module, usedBy } of uses) {
+            if (this.modules.has(module) || modules.includes(module))
+                continue;
+            for (const [name, guard] of Object.entries(module.guards)) {
+                claim("guard", name, usedBy, this.guards.has(name), guardModules);
+                guards[name] = guard;
+            }
+            const policies = Object.entries(module.rateLimitPolicies);
+            if (policies.length > 0 && !this.rateLimits.isConfigured) {
+                throw new Error(`Lambder: the module ${usedBy} declares rate-limit policies, and no rateLimits option was given at creation, ` +
+                    `which gives the limiter they count on. Pass rateLimits at creation; on a server its own policies may be left out (rateLimits: { limiter }).`);
+            }
+            for (const [name, policy] of policies) {
+                claim("rate-limit policy", name, usedBy, this.rateLimits.has(name), policyModules);
+                rateLimitPolicies[name] = policy;
+            }
+            modules.push(module);
+        }
+        return { modules, guards, rateLimitPolicies };
+    }
+    /** 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) {
+        this.guards.add(added.guards);
+        if (Object.keys(added.rateLimitPolicies).length > 0)
+            this.rateLimits.add(added.rateLimitPolicies);
+        for (const module of added.modules)
+            this.modules.add(module);
+    }
+    /**
+     * 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, adding) {
         const { name, mode } = definition;
         // Each subsystem reports its own absence: one combined message would
         // name all three when only one of them is missing.
         if (definition.rateLimit !== undefined && !this.rateLimits.isConfigured) {
             throw new Error(`Lambder: API "${name}" declares rateLimit but no rateLimits option was configured at creation.`);
         }
-        if (definition.guards !== undefined && !this.guards.isConfigured) {
+        if (definition.guards !== undefined && !this.guards.isConfigured && Object.keys(adding?.guards ?? {}).length === 0) {
             throw new Error(`Lambder: API "${name}" declares guards but no guards option was configured at creation.`);
         }
-        this.rateLimits.assertRegistration(name, mode, definition.rateLimit);
-        this.guards.assertRegistration(name, mode, definition.guards);
+        this.rateLimits.assertRegistration(name, mode, definition.rateLimit, adding?.rateLimitPolicies);
+        this.guards.assertRegistration(name, mode, definition.guards, adding?.guards);
         // `idempotency: false` is an explicit opt-out, not a use: it asks for
         // nothing and so needs no store behind it.
         if (usesIdempotency(definition)) {

package/dist/api/LambderApiRateLimits.d.ts

@@ -118,8 +118,12 @@ export type LambderApiRateLimitPolicyConfig<TCtx = any> = LambderRateLimitPolicy
 export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig<any>>> = {
     /** Your limiter instance (LambderDdbRateLimiter, LambderMemoryRateLimiter, or your own); its table and keyPrefix apply as configured on it. */
     limiter: LambderRateLimiter;
-    /** Named policies referenced (typed) from defineApi. */
-    policies: TPolicies;
+    /**
+     * Named policies referenced (typed) from defineApi. Left out where every
+     * policy is declared by the app's modules (defineApiModule), which count
+     * on this limiter; an empty map is refused.
+     */
+    policies?: TPolicies;
     /**
      * Let the request through when the limiter itself fails (the table is
      * down, an IAM action is missing), instead of failing the request.
@@ -270,6 +274,14 @@ export type LambderRateLimitOption<TPolicies> = LambderAllowedPolicyNames<TPolic
  *   session-keyed limits, before the guards, for "beforeGuards".
  */
 type LambderRateLimitPhase = "beforeSession" | LambderRateLimitChargeAt;
+/**
+ * Refuses a policy that cannot be counted: a per that is no key, no window,
+ * a window no limiter can act on, a chargeAt on a policy that takes none, a
+ * message carrying a code or data, an unknown budget. What the policies
+ * given at creation and a module's policies (defineApiModule) are each held
+ * to, one rule for both.
+ */
+export declare const assertRateLimitPolicyDeclaration: (name: string, policy: LambderApiRateLimitPolicyConfig) => void;
 /**
  * Runtime side of the rate-limit subsystem: holds the limiter and its named
  * policies, asserts API registrations against them at startup, and checks an
@@ -299,15 +311,34 @@ export declare class LambderApiRateLimitsEngine {
     constructor(keyFieldDigest: LambderKeyFieldDigest);
     /** True once rateLimits were configured. */
     get isConfigured(): boolean;
+    /** Whether a policy of this name is declared, by the creation's policies or a module added since. */
+    has(name: string): boolean;
+    /**
+     * Takes the limiter and the policies given at creation. The policies may
+     * be left out when every policy is a module's (defineApiModule), which
+     * counts on this limiter; an empty map is refused, as an empty guards
+     * map is.
+     */
     configure(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
+    /**
+     * Adds a module's policies beside the ones declared so far, counted on
+     * the limiter given at creation. Its names were checked against them
+     * before (LambderApiPipeline.modulesToAdd), so a name met again here is a
+     * caller that skipped that check.
+     */
+    add(policies: Readonly<Record<string, LambderApiRateLimitPolicyConfig>>): void;
     /**
      * Puts the engine over another limiter, for `lambder/testing`; the named
      * policies and failOpen stay as configured. False when rateLimits were
      * never configured: there is nothing for a limiter to sit under.
      */
     [LAMBDER_BACKEND_SWAP](limiter: LambderRateLimiter): boolean;
-    /** Startup validation of one API registration's rateLimit option. */
-    assertRegistration(apiName: string, mode: LambderApiMode, rateLimitOption?: LambderRateLimitOptionValue): void;
+    /**
+     * Startup validation of one API registration's rateLimit option.
+     * `adding` holds the policies of the modules the same registration adds,
+     * which the engine takes only once every endpoint of it passed.
+     */
+    assertRegistration(apiName: string, mode: LambderApiMode, rateLimitOption?: LambderRateLimitOptionValue, adding?: Readonly<Record<string, LambderApiRateLimitPolicyConfig>>): void;
     /**
      * Check the API's policies in declared order; the first exceeded one
      * refuses with a 429 envelope and a Retry-After header. Attempts count,

package/dist/api/LambderApiRateLimits.js

@@ -123,6 +123,37 @@ const windowsOf = (policy, override) => {
 const trackerKeyOf = (name, policy, apiName, key) => policy.budget === "perPolicy" || apiName === null
     ? joinKeyFields("policy", name, key)
     : joinKeyFields("api", apiName, name, key);
+/**
+ * Refuses a policy that cannot be counted: a per that is no key, no window,
+ * a window no limiter can act on, a chargeAt on a policy that takes none, a
+ * message carrying a code or data, an unknown budget. What the policies
+ * given at creation and a module's policies (defineApiModule) are each held
+ * to, one rule for both.
+ */
+export const assertRateLimitPolicyDeclaration = (name, policy) => {
+    const per = policy?.per;
+    if (per !== undefined && per !== "ip" && per !== "session" && typeof per?.handler !== "function") {
+        throw new Error(`Lambder: rate-limit policy "${name}" has a per that is not "ip", "session", or a { apiInput?, handler } key. Leave per out for a policy the handler charges with its own key.`);
+    }
+    if (!RATE_LIMIT_WINDOW_KEYS.some((key) => policy[key])) {
+        throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
+    }
+    assertWindowLimits(`rate-limit policy "${name}"`, policy);
+    const chargeAt = policy.chargeAt;
+    if (chargeAt !== undefined) {
+        if (chargeAt !== "beforeGuards" && chargeAt !== "afterGuards") {
+            throw new Error(`Lambder: rate-limit policy "${name}" has chargeAt "${String(chargeAt)}"; use "afterGuards" (default) or "beforeGuards".`);
+        }
+        if (per === undefined || per === "ip" || per === "session") {
+            throw new Error(`Lambder: rate-limit policy "${name}" sets chargeAt, which only a policy keyed by a { apiInput?, handler } key takes: per "ip" and per "session" each run at one fixed place, and a policy without per is charged by the code that names it.`);
+        }
+    }
+    assertRateLimitMessage(`rate-limit policy "${name}"`, policy.refusal);
+    const budget = policy.budget;
+    if (budget !== undefined && budget !== "perApi" && budget !== "perPolicy") {
+        throw new Error(`Lambder: rate-limit policy "${name}" has budget "${String(budget)}"; use "perApi" (default: each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
+    }
+};
 /**
  * Runtime side of the rate-limit subsystem: holds the limiter and its named
  * policies, asserts API registrations against them at startup, and checks an
@@ -157,40 +188,27 @@ export class LambderApiRateLimitsEngine {
     }
     /** True once rateLimits were configured. */
     get isConfigured() { return this.limiter !== null; }
+    /** Whether a policy of this name is declared, by the creation's policies or a module added since. */
+    has(name) { return this.policies.has(name); }
+    /**
+     * Takes the limiter and the policies given at creation. The policies may
+     * be left out when every policy is a module's (defineApiModule), which
+     * counts on this limiter; an empty map is refused, as an empty guards
+     * map is.
+     */
     configure(config) {
         if (this.limiter)
             throw new Error("Lambder: rateLimits were already configured.");
-        // Declaring the option is declaring a limit, as for the guards option
-        // and an API's own `rateLimit: {}`. An empty map would configure a
-        // limiter with nothing to enforce, and every API naming a policy would
-        // be reported as if the option were missing: the wrong line to fix.
-        if (Object.keys(config.policies).length === 0) {
-            throw new Error("Lambder: the rateLimits option was declared with no policies in it, which configures nothing. Name the policies APIs will declare, or leave the option off.");
-        }
-        for (const [name, policy] of Object.entries(config.policies)) {
-            const per = policy.per;
-            if (per !== undefined && per !== "ip" && per !== "session" && typeof per?.handler !== "function") {
-                throw new Error(`Lambder: rate-limit policy "${name}" has a per that is not "ip", "session", or a { apiInput?, handler } key. Leave per out for a policy the handler charges with its own key.`);
-            }
-            if (!RATE_LIMIT_WINDOW_KEYS.some((key) => policy[key])) {
-                throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
-            }
-            assertWindowLimits(`rate-limit policy "${name}"`, policy);
-            const chargeAt = policy.chargeAt;
-            if (chargeAt !== undefined) {
-                if (chargeAt !== "beforeGuards" && chargeAt !== "afterGuards") {
-                    throw new Error(`Lambder: rate-limit policy "${name}" has chargeAt "${String(chargeAt)}"; use "afterGuards" (default) or "beforeGuards".`);
-                }
-                if (per === undefined || per === "ip" || per === "session") {
-                    throw new Error(`Lambder: rate-limit policy "${name}" sets chargeAt, which only a policy keyed by a { apiInput?, handler } key takes: per "ip" and per "session" each run at one fixed place, and a policy without per is charged by the code that names it.`);
-                }
-            }
-            assertRateLimitMessage(`rate-limit policy "${name}"`, policy.refusal);
-            const budget = policy.budget;
-            if (budget !== undefined && budget !== "perApi" && budget !== "perPolicy") {
-                throw new Error(`Lambder: rate-limit policy "${name}" has budget "${String(budget)}"; use "perApi" (default: each referencing API counts separately) or "perPolicy" (one counter shared by every referencing API).`);
-            }
+        // Declaring the policies is declaring a limit, as for the guards
+        // option and an API's own `rateLimit: {}`. An empty map would
+        // configure a limiter with nothing to enforce, and every API naming a
+        // policy would be reported as if the option were missing: the wrong
+        // line to fix.
+        if (config.policies !== undefined && Object.keys(config.policies).length === 0) {
+            throw new Error("Lambder: the rateLimits option was declared with no policies in it, which configures nothing. Name the policies APIs will declare, or leave the policies out where the app's modules declare them all.");
         }
+        for (const [name, policy] of Object.entries(config.policies ?? {}))
+            assertRateLimitPolicyDeclaration(name, policy);
         const ipv6PrefixLength = config.ipv6PrefixLength ?? DEFAULT_IPV6_RATE_LIMIT_PREFIX;
         if (!Number.isInteger(ipv6PrefixLength) || ipv6PrefixLength < 1 || ipv6PrefixLength > 128) {
             throw new Error(`Lambder: rateLimits.ipv6PrefixLength must be a whole number from 1 to 128, got ${String(ipv6PrefixLength)}.`);
@@ -198,7 +216,24 @@ export class LambderApiRateLimitsEngine {
         this.limiter = config.limiter;
         this.failOpen = config.failOpen ?? true;
         this.ipv6PrefixLength = ipv6PrefixLength;
-        this.policies = new Map(Object.entries(config.policies));
+        this.policies = new Map(Object.entries(config.policies ?? {}));
+    }
+    /**
+     * Adds a module's policies beside the ones declared so far, counted on
+     * the limiter given at creation. Its names were checked against them
+     * before (LambderApiPipeline.modulesToAdd), so a name met again here is a
+     * caller that skipped that check.
+     */
+    add(policies) {
+        if (!this.limiter)
+            throw new Error("Lambder: rate-limit policies were added before a limiter was configured.");
+        for (const [name, policy] of Object.entries(policies)) {
+            if (this.policies.has(name))
+                throw new Error(`Lambder: rate-limit policy "${name}" is already defined.`);
+            assertRateLimitPolicyDeclaration(name, policy);
+        }
+        for (const [name, policy] of Object.entries(policies))
+            this.policies.set(name, policy);
     }
     /**
      * Puts the engine over another limiter, for `lambder/testing`; the named
@@ -211,8 +246,12 @@ export class LambderApiRateLimitsEngine {
         this.limiter = limiter;
         return true;
     }
-    /** Startup validation of one API registration's rateLimit option. */
-    assertRegistration(apiName, mode, rateLimitOption) {
+    /**
+     * Startup validation of one API registration's rateLimit option.
+     * `adding` holds the policies of the modules the same registration adds,
+     * which the engine takes only once every endpoint of it passed.
+     */
+    assertRegistration(apiName, mode, rateLimitOption, adding) {
         const entries = toRateLimitEntries(rateLimitOption);
         // Declaring the option is declaring a limit, as for guards: `{}`,
         // `[]` and `{ name: undefined }` would register an API that
@@ -222,9 +261,9 @@ export class LambderApiRateLimitsEngine {
                 `Name the policy that limits it, or omit the option entirely.`);
         }
         for (const { name, override } of entries) {
-            const policy = this.policies.get(name);
+            const policy = this.policies.get(name) ?? (adding && Object.prototype.hasOwnProperty.call(adding, name) ? adding[name] : undefined);
             if (!policy) {
-                throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it in the rateLimits option at creation.`);
+                throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it in the rateLimits option at creation, or, on a server, in the module the API is declared with (defineApiModule).`);
             }
             if (policy.per === undefined) {
                 throw new Error(`Lambder: API "${apiName}" references rate-limit policy "${name}", which declares no per: its key is the one a handler passes to ctx.rateLimit("${name}", key), so the request alone cannot be counted against it.`);

package/dist/core/Lambder.d.ts

@@ -12,21 +12,21 @@ import { LambderFiles } from "./LambderFiles.js";
 import { type LambderPipelineBackends, type LambderPipelineBackendSwap } from "../api/LambderApiPipeline.js";
 import type { LambderFileSource } from "../shared/contracts/LambderFileSource.js";
 import { LAMBDER_BACKEND_SWAP, LAMBDER_CRASH_WATCH } from "../shared/util/LambderTestingDoors.js";
-import { type LambderWireRefusalsOf, type LambderHandlerRefusalsOf, type LambderRefusalNamesIn, type LambderRefusalsOption, type LambderRefusalVocabularyOption, type LambderRefusalVocabularyOptionChecks, type LambderMergedRefusalVocabulary } from "../api/LambderApiRefusals.js";
+import { type LambderHandlerRefusalsOf, type LambderRefusalVocabularyOption, type LambderRefusalVocabularyOptionChecks, type LambderMergedRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import { type LambderDeclaredRefuse } from "../shared/wire/LambderApiRefusal.js";
 import { type LambderApiSignatureEntry } from "../api/LambderApiSignature.js";
 import { type LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { LambderApiOptionEntries } from "../shared/wire/LambderApiOptionEntries.js";
-import type { LambderApiIdempotencyOption } from "../shared/wire/LambderApiOptionValues.js";
-import type { LambderApiGuard, LambderGuardMetaMap, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusalNamesOf } from "../api/LambderApiGuards.js";
-import type { LambderApiRateLimitPolicyConfig, LambderRateLimitOption } from "../api/LambderApiRateLimits.js";
+import type { LambderApiGuard, LambderGuardMetaMap } from "../api/LambderApiGuards.js";
+import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
 import type { LambderApiIdempotencyConfig } from "../api/LambderApiIdempotency.js";
-import type { LambderContractEntry, LambderJsonOf } from "../shared/wire/LambderApiContract.js";
-import { type LambderActionNamesCheck, type LambderApiDeclaration, type LambderApiDeclarations, type LambderApiGroup, type LambderApiModeOf, type LambderAppTypes, type LambderContractOfGroups, type LambderGroupNameCheck, type LambderGroupPartsCheck, type LambderMergedParts, type LambderLazyApiGroup, type LambderPlainAppTypes, type LambderPublicSessionPolicyCheck, type LambderRegisteredGroupsCheck, type LambderRegistrableApiGroup, type LambderSessionModeCheck } from "../api/LambderApiDeclarations.js";
+import { type LambderAppTypes, type LambderContractOfGroups, type LambderPlainAppTypes, type LambderRegisteredGroupsCheck, type LambderRegistrableApiGroup } from "../api/LambderApiDeclarations.js";
+import { type LambderDefineApi, type LambderDefineApiGroup, type LambderDefineLazyApiGroup } from "./LambderApiBuilders.js";
+import { LambderApiModule, type LambderApiModuleOptionChecks, type LambderApiModuleOptions, type LambderModuleAppTypes } from "./LambderApiModule.js";
 import { type LambderHttpEvent, type LambderRenderContext, type LambderSessionRenderContext } from "./LambderContext.js";
-import type { LambderReadonlyDeep, MaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderMaybePromise } from "../shared/util/LambderTypeUtilities.js";
 import { type LambderCallSummary } from "./LambderCallSummary.js";
-import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderRouteHandler, type LambderInputValidationHandler, type LambderFallbackHandler, type LambderGlobalErrorHandler, type LambderAfterRenderHook, type LambderBeforeRenderHook, type LambderFallbackHook, type LambderActionTools, type LambderCreateOptions, type LambderGivenOption, type LambderHandler, type LambderNestedOptionChecks, type LambderObjectOutputCheck, type LambderPayloadSliceCheck, type LambderRequirableGuardsField, type LambderSessionEnabledInstance, type LambderSessionRouteHandler } from "./LambderCreateOptions.js";
+import { type LambderMergedNamedMaps, type LambderNamedMapsOption, type LambderRouteHandler, type LambderInputValidationHandler, type LambderFallbackHandler, type LambderGlobalErrorHandler, type LambderAfterRenderHook, type LambderBeforeRenderHook, type LambderFallbackHook, type LambderActionTools, type LambderCreateOptions, type LambderGivenOption, type LambderHandler, type LambderNestedOptionChecks, type LambderNoExtraKeys, type LambderSessionEnabledInstance, type LambderSessionRouteHandler } from "./LambderCreateOptions.js";
 /** Everything `lambder/testing` may put under a built instance: the pipeline's stores, and the source its files are read from. */
 export type LambderInstanceBackends = LambderPipelineBackends & {
     fileSource?: LambderFileSource;
@@ -44,17 +44,6 @@ export type LambderInstanceBackendSwap = LambderPipelineBackendSwap & {
  * class cannot be read without it.
  */
 export type LambderCreatedHook = (lambderInstance: Lambder<any, any>) => void | Promise<void>;
-/** The codes one API may refuse with, typed: its own refusals option's and its declared guards', as the vocabulary holds them. */
-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.
- */
-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"]>;
-};
 /**
  * Main Lambder class for building type-safe serverless APIs. Create
  * instances with initLambder<SessionData>().create({...}) (see below): the
@@ -117,10 +106,15 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
     private readonly apiGroupNames;
     /** The lazy groups not loaded yet, each with its load in progress, if one is. */
     private readonly lazyApiGroups;
-    /** 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. */
-    private readonly guards;
-    /** The rate-limit policies given at creation, kept for apiOptionEntries(), which records each one less its key handler. */
-    private readonly rateLimitPolicies;
+    /**
+     * 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().
+     */
+    private guards;
+    /** 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. */
+    private rateLimitPolicies;
     /** The refusal vocabulary given at creation: what each API's and each guard's refusal codes resolve against. Null without the option. */
     private readonly refusalVocabulary;
     /** Every API's refusals option as written, for apiOptionEntries(); its definition holds the resolved set. */
@@ -150,7 +144,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;
@@ -186,73 +180,50 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * res.templateFile (markers optional) with no-cache.
      */
     serveIndexHtml(handler?: LambderFallbackHandler, options?: LambderIndexHtmlOptions): this;
-    addRoute<TPath extends LambderRoutePath>(condition: TPath, actionFn: (ctx: LambderRenderContext<any, LambderPathParamsOf<TPath>, {}, TApp["session"], TApp["policies"]>, resolver: LambderResolver) => MaybePromise<LambderResponse>): this;
+    addRoute<TPath extends LambderRoutePath>(condition: TPath, actionFn: (ctx: LambderRenderContext<any, LambderPathParamsOf<TPath>, {}, TApp["session"], TApp["policies"]>, resolver: LambderResolver) => LambderMaybePromise<LambderResponse>): this;
     addRoute(condition: RegExp | LambderRouteConditionFn | LambderRouteMatcher, actionFn: LambderRouteHandler): this;
-    addSessionRoute<TPath extends LambderRoutePath>(condition: TPath, actionFn: ((ctx: LambderSessionRenderContext<any, TApp["session"], LambderPathParamsOf<TPath>, {}, TApp["policies"]>, resolver: LambderResolver) => MaybePromise<LambderResponse>) & LambderSessionEnabledInstance<TApp["sessions"]>): this;
+    addSessionRoute<TPath extends LambderRoutePath>(condition: TPath, actionFn: ((ctx: LambderSessionRenderContext<any, TApp["session"], LambderPathParamsOf<TPath>, {}, TApp["policies"]>, resolver: LambderResolver) => LambderMaybePromise<LambderResponse>) & LambderSessionEnabledInstance<TApp["sessions"]>): this;
     addSessionRoute(condition: RegExp | LambderRouteConditionFn | LambderRouteMatcher, actionFn: LambderSessionRouteHandler<TApp["session"]> & LambderSessionEnabledInstance<TApp["sessions"]>): this;
     /**
-     * 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, 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.
+     */
+    readonly defineApi: LambderDefineApi<TApp>;
+    /** Gathers endpoints into a named group (see LambderDefineApiGroup). */
+    readonly defineApiGroup: LambderDefineApiGroup;
+    /** A group loaded on the first call to one of its endpoints (see LambderDefineLazyApiGroup). */
+    readonly lazyApiGroup: LambderDefineLazyApiGroup;
+    /**
+     * 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.
      *
-     * An arrow property rather than a method, so an app can hand it out
-     * detached: `export const { defineApi, defineApiGroup } = lambderApp;`.
-     */
-    readonly defineApi: <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>) => MaybePromise<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).
+     * ```typescript
+     * export const giftCardModule = storeApp.defineApiModule({
+     *     guards: { cardHolder },
+     *     rateLimitPolicies: { redeemPerCard: { perHour: 5, per: "session" } },
+     * });
+     * ```
      *
-     * 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.
+     * 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.
      */
-    readonly defineApiGroup: <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.
-     */
-    readonly lazyApiGroup: <const TName extends string, TGroup extends LambderApiGroup<TName, any>>(name: TName & LambderGroupNameCheck<TName>, load: () => Promise<TGroup>) => LambderLazyApiGroup<TName, NoInfer<TGroup>>;
+    defineApiModule<const TOptions extends LambderApiModuleOptions<TApp["session"]>>(options: LambderNoExtraKeys<TOptions, LambderApiModuleOptions<TApp["session"]>> & LambderApiModuleOptionChecks<TApp, TOptions>): LambderApiModule<LambderModuleAppTypes<TApp, LambderGivenOption<TOptions, "guards">, LambderGivenOption<TOptions, "rateLimitPolicies">>>;
     /**
      * Registers groups of endpoints, as one contract: `typeof
      * lambder.ApiContract` then maps every `group.action` to its entry, one
@@ -299,7 +270,12 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * group answers each of them as an eager one does.
      */
     private registeredDefinitionOf;
-    /** The endpoints of one group, each checked as `group.action`; nothing is registered until they are committed. */
+    /**
+     * 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.
+     */
     private prepareApiGroup;
     /**
      * A lazy group, loaded once: its import, checked to be the group it was
@@ -337,8 +313,8 @@ export default class Lambder<TApp extends LambderAppTypes = LambderPlainAppTypes
      * Use a type-guard filter to get a typed event:
      * `(event): event is ScheduledEvent => ...`
      */
-    addAction<TEvent>(filter: (event: unknown, ctx: LambderRenderContext | null) => event is TEvent, actionFn: (event: TEvent, tools: LambderActionTools) => MaybePromise<unknown>): this;
-    addAction(filter: (event: unknown, ctx: LambderRenderContext | null) => boolean, actionFn: (event: unknown, tools: LambderActionTools) => MaybePromise<unknown>): this;
+    addAction<TEvent>(filter: (event: unknown, ctx: LambderRenderContext | null) => event is TEvent, actionFn: (event: TEvent, tools: LambderActionTools) => LambderMaybePromise<unknown>): this;
+    addAction(filter: (event: unknown, ctx: LambderRenderContext | null) => boolean, actionFn: (event: unknown, tools: LambderActionTools) => LambderMaybePromise<unknown>): this;
     /**
      * Hands the instance to a function that registers on it (routes, hooks,
      * actions) and continues the chain with what it returns. Endpoints are
@@ -464,8 +440,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 +472,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;
     /**
@@ -701,4 +677,3 @@ export declare const initLambder: <TSessionData = any>() => {
     guard: import("../api/LambderApiGuards.js").LambderGuardBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>, LambderSessionRenderContext<any, TSessionData>, {}, false>;
     rateLimitKey: import("../api/LambderApiRateLimits.js").LambderRateLimitKeyBuilder<LambderRenderContext<any, Record<string, string>, {}, TSessionData>>;
 };
-export {};