lambder 15.0.2 → 16.0.1

package/dist/core/LambderApiModule.d.ts

@@ -0,0 +1,106 @@
+import type { LambderAppTypes, LambderPlainAppTypes } from "../api/LambderApiDeclarations.js";
+import type { LambderApiModuleDeclarations } from "../api/LambderApiModules.js";
+import type { LambderGuardMetaMap } from "../api/LambderApiGuards.js";
+import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
+import type { LambderMergedNamedMaps, LambderNamedMapsOption } from "../shared/util/LambderNamedMaps.js";
+import { type LambderDefineApi, type LambderDefineApiGroup, type LambderDefineLazyApiGroup } from "./LambderApiBuilders.js";
+import type { LambderGivenOption, LambderGuardChecks, LambderGuardsMap, LambderRateLimitPoliciesMap, LambderRateLimitPolicyChecks } from "./LambderCreateOptions.js";
+/**
+ * What defineApiModule() takes: the guards and the rate-limit policies a
+ * module declares for its own endpoints, each one map or a list of maps, as
+ * create() takes its own. The guards are pinned to the app's session type,
+ * as create()'s are.
+ */
+export type LambderApiModuleOptions<TSessionData = any> = {
+    /** The module's guards, which its endpoints name beside the instance's: one map, or a list of maps merged in order. */
+    guards?: LambderNamedMapsOption<LambderGuardsMap<TSessionData>>;
+    /** The module's rate-limit policies, counted on the instance's limiter, which its endpoints name beside the instance's: one map, or a list of maps merged in order. */
+    rateLimitPolicies?: LambderNamedMapsOption<LambderRateLimitPoliciesMap>;
+};
+/** Every name a map, or each map of a list, declares. */
+type LambderNamesDeclaredBy<TMaps> = TMaps extends readonly unknown[] ? {
+    [TIndex in keyof TMaps]: keyof TMaps[TIndex];
+}[number] : keyof TMaps;
+/** A module's map held to declaring names of its own: one the instance declares is a compile error, and the property name is the message. */
+type LambderModuleNamesCheck<TMaps, TInstanceNames> = [
+    Extract<LambderNamesDeclaredBy<TMaps>, TInstanceNames>
+] extends [never] ? unknown : {
+    readonly "lambder: the instance declares these names already; a module declares names of its own": Extract<LambderNamesDeclaredBy<TMaps>, TInstanceNames>;
+};
+/**
+ * defineApiModule()'s options held to what create() holds its own to, one
+ * level down (each guard and each policy checked for surplus keys, a guard's
+ * refusal codes held to the vocabulary, a name two maps of a list declare
+ * refused), and to declaring no name the instance declares.
+ */
+export type LambderApiModuleOptionChecks<TApp extends LambderAppTypes, TOptions extends LambderApiModuleOptions<TApp["session"]>> = {
+    guards?: LambderGuardChecks<TApp["session"], NonNullable<LambderGivenOption<TOptions, "guards">>, TApp["refusals"]> & LambderModuleNamesCheck<NonNullable<LambderGivenOption<TOptions, "guards">>, keyof TApp["guards"]>;
+    rateLimitPolicies?: LambderRateLimitPolicyChecks<NonNullable<LambderGivenOption<TOptions, "rateLimitPolicies">>> & LambderModuleNamesCheck<NonNullable<LambderGivenOption<TOptions, "rateLimitPolicies">>, keyof TApp["policies"]>;
+} & LambderModuleDeclaresSomething<TOptions>;
+/**
+ * A module declaring neither guards nor policies, refused as an empty guards
+ * option is: its builders would be the instance's own. The property name is
+ * the message.
+ */
+type LambderModuleDeclaresSomething<TOptions> = [
+    LambderGivenOption<TOptions, "guards"> | LambderGivenOption<TOptions, "rateLimitPolicies">
+] extends [undefined] ? {
+    readonly "lambder: a module declares guards or rate-limit policies of its own; one with neither declares its endpoints with the instance's builders": never;
+} : unknown;
+/** One map from what a module option was given: a list merged, a lone map as it is, nothing for an option left out. */
+type LambderModuleMap<TOption> = [TOption] extends [undefined] ? {} : LambderMergedNamedMaps<TOption>;
+/**
+ * The app types a module's builders are typed on: the instance's, with the
+ * module's guards and rate-limit policies beside the instance's own. Its
+ * endpoints name either, and nothing else.
+ */
+export type LambderModuleAppTypes<TApp extends LambderAppTypes, TGuards, TPolicies> = {
+    session: TApp["session"];
+    policies: TApp["policies"] & (LambderModuleMap<TPolicies> extends infer TMerged extends Record<string, LambderApiRateLimitPolicyConfig> ? TMerged : {});
+    guards: TApp["guards"] & LambderGuardMetaMap<LambderModuleMap<TGuards>>;
+    idempotency: TApp["idempotency"];
+    guardsRequired: TApp["guardsRequired"];
+    sessions: TApp["sessions"];
+    refusals: TApp["refusals"];
+    refusalCodesRequired: TApp["refusalCodesRequired"];
+};
+/**
+ * A part of an app with guards and rate-limit policies of its own, for its
+ * own endpoints: the declaration builders typed on its instance's types with
+ * the module's guards and policies beside the instance's. Made by an
+ * instance's defineApiModule(); its endpoints are registered on the instance
+ * as any are (registerApiGroups), and their registration adds the module's
+ * guards and policies to the instance, refusing a name the instance or
+ * another module declares.
+ *
+ * So an app's core creates its instance knowing only its own policies, and
+ * each module brings its own: nothing has to import every module's guards
+ * before the instance can exist. Hand the builders out under the module's
+ * name, as an instance's are:
+ *
+ * ```typescript
+ * export const giftCardModule = storeApp.defineApiModule({ guards: { cardHolder }, rateLimitPolicies: { redeemPerCard } });
+ * export type GiftCardModule = typeof giftCardModule;
+ * export const defineApi: GiftCardModule["defineApi"] = giftCardModule.defineApi;
+ * ```
+ *
+ * @typeParam TApp - @internal The module's app types (LambderModuleAppTypes): the instance's, widened by the module's guards and policies (do not pass manually)
+ */
+export declare class LambderApiModule<TApp extends LambderAppTypes = LambderPlainAppTypes> {
+    /**
+     * Type property for the module's app types, as an instance's AppTypes
+     * is: what LambderRenderContextOf<typeof module> reads, for a helper
+     * handed one of the module's handler contexts, its policies typed. It
+     * has no value.
+     */
+    readonly AppTypes: TApp;
+    /** Declares one of the module's endpoints: its guards and rate limits may name the instance's and the module's own. */
+    readonly defineApi: LambderDefineApi<TApp>;
+    /** Gathers endpoints into a named group, as the instance's does. */
+    readonly defineApiGroup: LambderDefineApiGroup;
+    /** A group of the module's loaded on the first call to it, carrying the module, so its guards and policies are added when the group is registered. */
+    readonly lazyApiGroup: LambderDefineLazyApiGroup;
+    /** Called by an instance's defineApiModule(), with the declarations it checked; an app does not construct one. */
+    constructor(declarations: LambderApiModuleDeclarations);
+}
+export {};

package/dist/core/LambderApiModule.js

@@ -0,0 +1,45 @@
+import { apiBuildersFor, } from "./LambderApiBuilders.js";
+/**
+ * A part of an app with guards and rate-limit policies of its own, for its
+ * own endpoints: the declaration builders typed on its instance's types with
+ * the module's guards and policies beside the instance's. Made by an
+ * instance's defineApiModule(); its endpoints are registered on the instance
+ * as any are (registerApiGroups), and their registration adds the module's
+ * guards and policies to the instance, refusing a name the instance or
+ * another module declares.
+ *
+ * So an app's core creates its instance knowing only its own policies, and
+ * each module brings its own: nothing has to import every module's guards
+ * before the instance can exist. Hand the builders out under the module's
+ * name, as an instance's are:
+ *
+ * ```typescript
+ * export const giftCardModule = storeApp.defineApiModule({ guards: { cardHolder }, rateLimitPolicies: { redeemPerCard } });
+ * export type GiftCardModule = typeof giftCardModule;
+ * export const defineApi: GiftCardModule["defineApi"] = giftCardModule.defineApi;
+ * ```
+ *
+ * @typeParam TApp - @internal The module's app types (LambderModuleAppTypes): the instance's, widened by the module's guards and policies (do not pass manually)
+ */
+export class LambderApiModule {
+    /**
+     * Type property for the module's app types, as an instance's AppTypes
+     * is: what LambderRenderContextOf<typeof module> reads, for a helper
+     * handed one of the module's handler contexts, its policies typed. It
+     * has no value.
+     */
+    AppTypes;
+    /** Declares one of the module's endpoints: its guards and rate limits may name the instance's and the module's own. */
+    defineApi;
+    /** Gathers endpoints into a named group, as the instance's does. */
+    defineApiGroup;
+    /** A group of the module's loaded on the first call to it, carrying the module, so its guards and policies are added when the group is registered. */
+    lazyApiGroup;
+    /** Called by an instance's defineApiModule(), with the declarations it checked; an app does not construct one. */
+    constructor(declarations) {
+        const builders = apiBuildersFor(declarations);
+        this.defineApi = builders.defineApi;
+        this.defineApiGroup = builders.defineApiGroup;
+        this.lazyApiGroup = builders.lazyApiGroup;
+    }
+}

package/dist/core/LambderCallSummary.d.ts

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

package/dist/core/LambderCreateOptions.d.ts

@@ -19,15 +19,15 @@ import { type LambderRefusalVocabulary } from "../api/LambderApiRefusals.js";
 import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
 import type { LambderGuardNamesIn, LambderJsonOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderRateLimitMessage } from "../shared/wire/LambderApiOptionValues.js";
-import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
-export type LambderRouteHandler = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
-export type LambderSessionRouteHandler<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => MaybePromise<LambderResponse>;
+import type { LambderMaybePromise } from "../shared/util/LambderTypeUtilities.js";
+export type LambderRouteHandler = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderMaybePromise<LambderResponse>;
+export type LambderSessionRouteHandler<SessionData = any> = (ctx: LambderSessionRenderContext<any, SessionData>, resolver: LambderResolver) => LambderMaybePromise<LambderResponse>;
 export type LambderHookEvent = "created" | "beforeRender" | "afterRender" | "fallback";
 /** Return the (possibly replaced) ctx to continue, a LambderResponse to short-circuit, or an Error to fail. */
-export type LambderBeforeRenderHook = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderRenderContext | LambderResponse | Error>;
-export type LambderAfterRenderHook = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResponse) => MaybePromise<LambderResponse | Error>;
+export type LambderBeforeRenderHook = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderMaybePromise<LambderRenderContext | LambderResponse | Error>;
+export type LambderAfterRenderHook = (ctx: LambderRenderContext, resolver: LambderResolver, response: LambderResponse) => LambderMaybePromise<LambderResponse | Error>;
 export type LambderFallbackHook = (ctx: LambderRenderContext, resolver: LambderResolver) => void | Promise<void>;
-export type LambderGlobalErrorHandler = (err: Error, ctx: LambderRenderContext | null, response: LambderResponseBuilder) => MaybePromise<LambderResponse>;
+export type LambderGlobalErrorHandler = (err: Error, ctx: LambderRenderContext | null, response: LambderResponseBuilder) => LambderMaybePromise<LambderResponse>;
 /**
  * Where a crash happened.
  *
@@ -68,7 +68,7 @@ export type LambderCrashSite = {
  * password in the body, the session record): forward the fields a crash
  * needs rather than the whole context to an error tracker.
  */
-export type LambderCrashReporter = (error: Error, site: LambderCrashSite) => MaybePromise<void>;
+export type LambderCrashReporter = (error: Error, site: LambderCrashSite) => LambderMaybePromise<void>;
 /** The `crashes` option of create(). */
 export type LambderCrashOptions = {
     /** Told every crash on every path; see LambderCrashReporter. Default: none, and the framework's own 500 logs the crash to the console instead. */
@@ -88,10 +88,10 @@ export type LambderCrashOptions = {
      * writes its own answer, and describeCrash is there for it. A reveal
      * that throws counts as no. Default: nobody.
      */
-    reveal?: (ctx: LambderRenderContext) => MaybePromise<boolean>;
+    reveal?: (ctx: LambderRenderContext) => LambderMaybePromise<boolean>;
 };
-export type LambderFallbackHandler = (ctx: LambderRenderContext, resolver: LambderResolver) => MaybePromise<LambderResponse>;
-export type LambderInputValidationHandler = (ctx: LambderRenderContext, resolver: LambderResolver, zodError: z.ZodError) => MaybePromise<LambderResponse>;
+export type LambderFallbackHandler = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderMaybePromise<LambderResponse>;
+export type LambderInputValidationHandler = (ctx: LambderRenderContext, resolver: LambderResolver, zodError: z.ZodError) => LambderMaybePromise<LambderResponse>;
 /**
  * Second argument of an addAction handler. Discriminated on `ctx`: HTTP
  * invocations get the full context and a resolver, non-HTTP invocations get
@@ -107,7 +107,7 @@ export type LambderActionTools = {
     lambdaContext: Context;
 };
 export type LambderActionFilter = (event: unknown, ctx: LambderRenderContext | null) => boolean;
-export type LambderActionHandler<TEvent = unknown> = (event: TEvent, tools: LambderActionTools) => MaybePromise<unknown>;
+export type LambderActionHandler<TEvent = unknown> = (event: TEvent, tools: LambderActionTools) => LambderMaybePromise<unknown>;
 /** Overloaded handler type returned by getHandler(): HTTP events get a typed response, others dispatch to actions. */
 export type LambderHandler = {
     (event: LambderHttpEvent, context: Context): Promise<LambderHttpResponse>;
@@ -170,8 +170,12 @@ export type LambderGuardsMap<TSessionData = any> = Record<string, LambderApiGuar
 export type LambderRateLimitPoliciesMap = Record<string, LambderApiRateLimitPolicyConfig<LambderRenderContext>>;
 /** The `rateLimits` option of create(): the engine's config, with `policies` as one map or a list of maps. */
 export type LambderCreateRateLimitsOption = Omit<LambderApiRateLimitsConfig<LambderRateLimitPoliciesMap>, "policies"> & {
-    /** Named policies referenced (typed) from defineApi: one map, or a list of maps merged in order. */
-    policies: LambderNamedMapsOption<LambderRateLimitPoliciesMap>;
+    /**
+     * Named policies referenced (typed) from defineApi: one map, or a list of
+     * maps merged in order. Left out where every policy is declared by the
+     * app's modules (defineApiModule), which count on this limiter.
+     */
+    policies?: LambderNamedMapsOption<LambderRateLimitPoliciesMap>;
 };
 /** The options as the instance holds them: the guards and the rate-limit policies merged into one map each. */
 export type LambderMergedCreateOptions<TSessionData = any> = Omit<LambderCreateOptions<TSessionData>, "guards" | "rateLimits"> & {
@@ -292,14 +296,15 @@ export type LambderCreateOptions<TSessionData = any> = {
      */
     originProof?: LambderOriginProof;
     /**
-     * One summary per API call, written when the call is answered: the
-     * endpoint, how it ended (success, a refusal and its code, a flag, a
-     * validation refusal, a crash), the status, the duration and the
-     * handler's own time, whether an idempotent answer was replayed, whether
-     * the invocation was the process's first, and its request id with the
-     * id of the invocation that called it over invoke. Nothing from the
-     * input, the session, the cookies or the caller's address. See
-     * LambderCallSummary.
+     * One summary per API call, and per request a route answered, written
+     * when it is answered: the endpoint or the route as registered, how it
+     * ended (success, a refusal and its code, a flag, a validation refusal, a
+     * crash; a route's read from its status), the status, the duration and
+     * the handler's own time, whether an idempotent answer was replayed,
+     * whether the invocation was the process's first, and its request id
+     * with the id of the invocation that called it over invoke. Nothing from
+     * the input, the path, the session, the cookies or the caller's address.
+     * See LambderCallSummary.
      *
      * Default: each summary as one JSON line on stdout, which a Lambda
      * function's log group keeps and CloudWatch Logs Insights reads field by
@@ -474,7 +479,7 @@ type LambderGuardRefusalsKnown<TGuard, TRefusals> = TGuard extends {
     refusals: readonly (keyof NonNullable<TRefusals> & string)[];
 } : unknown : unknown;
 /** Every policy in a map, or in each map of a list, held to the policy shape, its message included; a list also declares no name twice. */
-type LambderRateLimitPolicyChecks<TPolicies> = TPolicies extends readonly unknown[] ? {
+export type LambderRateLimitPolicyChecks<TPolicies> = TPolicies extends readonly unknown[] ? {
     [TIndex in keyof TPolicies]: LambderRateLimitPolicyChecks<TPolicies[TIndex]>;
 } & LambderNoRepeatedNames<TPolicies> : {
     [TPolicy in keyof TPolicies]: LambderNoExtraKeys<TPolicies[TPolicy], LambderApiRateLimitPolicyConfig<LambderRenderContext>> & (TPolicies[TPolicy] extends {
@@ -484,7 +489,7 @@ type LambderRateLimitPolicyChecks<TPolicies> = TPolicies extends readonly unknow
     } : unknown);
 };
 /** Every guard in a map, or in each map of a list, held to the guard shape and its refusals to the vocabulary; a list also declares no name twice. */
-type LambderGuardChecks<TSessionData, TGuards, TRefusals> = TGuards extends readonly unknown[] ? {
+export type LambderGuardChecks<TSessionData, TGuards, TRefusals> = TGuards extends readonly unknown[] ? {
     [TIndex in keyof TGuards]: LambderGuardChecks<TSessionData, TGuards[TIndex], TRefusals>;
 } & LambderNoRepeatedNames<TGuards> : {
     [TGuard in keyof TGuards]: LambderNoExtraKeys<TGuards[TGuard], LambderGuardsMap<TSessionData>[string]> & LambderGuardRefusalsKnown<TGuards[TGuard], TRefusals>;
@@ -509,7 +514,7 @@ export type LambderNestedOptionChecks<TSessionData, TOptions extends LambderCrea
     crashes?: LambderNoExtraKeys<NonNullable<TOptions["crashes"]>, LambderOptionShape<TSessionData, "crashes">>;
     originProof?: LambderNoExtraKeys<NonNullable<TOptions["originProof"]>, LambderOptionShape<TSessionData, "originProof">>;
     rateLimits?: LambderNoExtraKeys<NonNullable<TOptions["rateLimits"]>, LambderOptionShape<TSessionData, "rateLimits">> & {
-        policies?: LambderRateLimitPolicyChecks<NonNullable<TOptions["rateLimits"]>["policies"]>;
+        policies?: LambderRateLimitPolicyChecks<NonNullable<NonNullable<TOptions["rateLimits"]>["policies"]>>;
     };
     guards?: LambderGuardChecks<TSessionData, NonNullable<TOptions["guards"]>, TRefusals>;
     files?: TOptions["files"] extends {

package/dist/core/LambderInvocationScope.d.ts

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

package/dist/core/LambderRouting.d.ts

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

package/dist/core/LambderRouting.js

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

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
-export type { LambderCreatedHook } from './core/Lambder.js';
-export type { LambderAppTypes, LambderPlainAppTypes, LambderApiDeclaration, LambderApiDeclarations, LambderApiGroup, LambderLazyApiGroup, LambderRegistrableApiGroup, LambderApiModeOf, LambderEntryOf, LambderContractOfGroups, } from './api/LambderApiDeclarations.js';
+export type { LambderCreatedHook, LambderInitCreateOptions } from './core/Lambder.js';
+export type { LambderDefineApi, LambderDefineApiGroup, LambderDefineLazyApiGroup, LambderApiHandlerContext, } from './core/LambderApiBuilders.js';
+export { LambderApiModule } from './core/LambderApiModule.js';
+export type { LambderApiModuleOptions, LambderApiModuleOptionChecks, LambderModuleAppTypes } from './core/LambderApiModule.js';
+export type { LambderApiModuleDeclarations } from './api/LambderApiModules.js';
+export type { LambderAppTypes, LambderPlainAppTypes, LambderApiDeclaration, LambderApiDeclarations, LambderApiGroup, LambderLazyApiGroup, LambderRegistrableApiGroup, LambderApiModeOf, LambderEntryOf, LambderContractOfGroups, LambderRegisteredGroupsCheck, LambderActionNamesCheck, LambderGroupNameCheck, LambderGroupPartsCheck, LambderMergedParts, LambderPublicSessionPolicyCheck, LambderSessionModeCheck, } from './api/LambderApiDeclarations.js';
 export { apiCallPath, apiNameOfCallPath, splitApiName, isGroupName, isActionName, LAMBDER_API_NAME_SEGMENT, LAMBDER_CALLER_MEMBER_NAMES, LAMBDER_RESERVED_GROUP_NAMES, LAMBDER_RESERVED_ACTION_NAMES, } from './shared/wire/LambderApiNames.js';
 export type { LambderReservedGroupName, LambderReservedActionName } from './shared/wire/LambderApiNames.js';
 export type { LambderContractGroupsOf, LambderContractNamesInGroup, LambderContractActionOf } from './shared/wire/LambderApiGroupCalls.js';
@@ -77,7 +81,7 @@ export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core
 export type { LambderResponseOptions, LambderRawResponseInit, LambderTemplateFileOptions, } from "./core/LambderResponseBuilder.js";
 export type { LambderRouteMatcher, LambderRouteConditionFn, LambderRouteCondition, LambderPathParamsOf, LambderRoutePath } from "./core/LambderRouting.js";
 export type { LambderCorsConfig } from "./core/LambderCors.js";
-export type { LambderCreateOptions, LambderSessionOptions, LambderActionTools, LambderHandler, } from "./core/LambderCreateOptions.js";
+export type { LambderCreateOptions, LambderSessionOptions, LambderActionTools, LambderHandler, LambderGivenOption, LambderNamedMapsOption, LambderMergedNamedMaps, LambderNestedOptionChecks, LambderObjectOutputCheck, LambderPayloadSliceCheck, LambderRequirableGuardsField, LambderSessionEnabledInstance, } from "./core/LambderCreateOptions.js";
 export type { LambderIndexHtmlOptions } from "./core/LambderIndexHtml.js";
 export type { LambderRouteHandler, LambderSessionRouteHandler, LambderActionHandler, LambderActionFilter, LambderHookEvent, LambderBeforeRenderHook, LambderAfterRenderHook, LambderFallbackHook, LambderGlobalErrorHandler, LambderFallbackHandler, LambderInputValidationHandler, LambderCrashOptions, LambderCrashReporter, LambderCrashSite, } from "./core/LambderCreateOptions.js";
 export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
@@ -136,10 +140,11 @@ export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
 export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderGuardNamesInputLacks, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, LambderGuardRefusals, LambderGuardRefusalNamesOf, } from "./api/LambderApiGuards.js";
 export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
-export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderRefusalVocabularyOption, LambderMergedRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
+export type { LambderRefusalDeclaration, LambderRefusalVocabulary, LambderRefusalVocabularyOption, LambderRefusalVocabularyOptionChecks, LambderMergedRefusalVocabulary, LambderApiAllowedRefusal, LambderApiAllowedRefusals, LambderEndpointRefusals, LambderRefusalsOption, LambderRefusalNamesIn, LambderHandlerRefusalsOf, LambderWireRefusalsOf, } from "./api/LambderApiRefusals.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
-export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderPolicyNamesInputLacks, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
+export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderPolicyNamesInputLacks, LambderRateLimitOption, LambderPolicyPerOf, } from "./api/LambderApiRateLimits.js";
+export type { LambderMaybePromise, LambderNoExtraKeys } from "./shared/util/LambderTypeUtilities.js";
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
 export type { LambderGuardsOptionValue, LambderRateLimitMessage, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderRefusalsOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { apiGuardParam, apiGuardParamExportName, apisWithGuard } from "./shared/wire/LambderApiOptionEntries.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
+// Modules: guards and rate-limit policies a part of an app declares for its own endpoints.
+export { LambderApiModule } from './core/LambderApiModule.js';
 // How an endpoint is named, and where a call to it goes.
 export { apiCallPath, apiNameOfCallPath, splitApiName, isGroupName, isActionName, LAMBDER_API_NAME_SEGMENT, LAMBDER_CALLER_MEMBER_NAMES, LAMBDER_RESERVED_GROUP_NAMES, LAMBDER_RESERVED_ACTION_NAMES, } from './shared/wire/LambderApiNames.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";

package/dist/mock/LambderMockApiModule.d.ts

@@ -0,0 +1,70 @@
+import type { z } from "zod";
+import type { LambderApiContractShape } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiGuard } from "../api/LambderApiGuards.js";
+import type { LambderRefusalVocabulary } from "../api/LambderApiRefusals.js";
+import type { LambderMockGuardsAgree, LambderMockGuardShapes } from "./LambderMockCreateOptions.js";
+import type { LambderMockCallContext, LambderMockEntry, LambderMockEntryGuardsCheck, LambderMockEntryInput, LambderMockGuardMapChecks, LambderMockHandler, LambderMockNotMockedGuardsCheck, LambderMockNotMockedInput, LambderMockOverride, LambderMockSessionCallContext, LambderMockSlice } from "./LambderMockTypes.js";
+/**
+ * What a mock app's defineApiModule() takes: the mock guards a part of the
+ * app declares for its own endpoints, standing in for the guards the
+ * server's module declares (its defineApiModule), as create()'s guards stand
+ * in for the server instance's. One map.
+ *
+ * No rate-limit policies: a mock takes every policy at create(), from the
+ * generated table the server writes (lambderMockPoliciesFrom), the module's
+ * among them, so none is restated by hand here.
+ */
+export type LambderMockApiModuleOptions<S = any> = {
+    /** The module's mock guards, one per guard the server's module declares, built with the mock init's guard(). */
+    guards: Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>>;
+};
+/** A module's map held to declaring names of its own: one the mock app's create() declares is a compile error, and the property name is the message. */
+type LambderMockModuleNamesCheck<MG, TAppNames> = [
+    Extract<keyof MG, TAppNames>
+] extends [never] ? unknown : {
+    readonly "lambder: the mock app declares these guards already; a module declares guards of its own": Extract<keyof MG, TAppNames>;
+};
+/**
+ * A module's mock guards held to what create()'s are held to: the contract,
+ * the generated guard declarations when the app was given them, surplus
+ * keys, and names of their own.
+ */
+export type LambderMockApiModuleChecks<C, S, G, D, TOptions extends LambderMockApiModuleOptions<S>> = {
+    guards: LambderMockGuardMapChecks<C, S, TOptions["guards"]> & LambderMockGuardShapes<S, TOptions["guards"]> & LambderMockGuardsAgree<TOptions["guards"], D> & LambderMockModuleNamesCheck<TOptions["guards"], keyof G>;
+};
+/**
+ * What a mock module asks of the app that made it: the app's own entry
+ * builders, given the module's declarations. The constructor's parameter,
+ * which the app's defineApiModule() passes; an app does not build one.
+ */
+export type LambderMockApiModuleDoor = {
+    api: (name: string, entry: unknown) => LambderMockEntry<any, any>;
+    notMocked: (name: string, input: unknown) => LambderMockEntry<any, any>;
+    apiSlice: (...entries: readonly LambderMockEntry<any, any>[]) => unknown;
+    override: (name: string, handler: unknown) => LambderMockOverride;
+};
+/**
+ * A part of a mock app with mock guards of its own: the app's entry builders,
+ * typed with the module's guards beside the app's. Made by the mock app's
+ * defineApiModule(); its entries are registered as any are (register,
+ * registerPartial), and registering them adds the module's guards to the
+ * app, refusing a name the app or another module declares. The mock twin of
+ * the server's LambderApiModule, so a module's mock guards are declared with
+ * the module's mocks, and the app's own setup imports none of them.
+ *
+ * `G` is the app's guards and the module's together, which is what the
+ * entries' handlers read guardData by.
+ */
+export declare class LambderMockApiModule<C extends LambderApiContractShape, S = any, G extends Record<string, LambderApiGuard<any, any, any>> = {}, TDerived extends boolean = false, TVocabulary extends LambderRefusalVocabulary = never, TCodesRequired extends boolean = false> {
+    private readonly door;
+    constructor(door: LambderMockApiModuleDoor);
+    /** A mock for one of the module's endpoints, as the app's api() builds one: its guards may be the app's and the module's own. */
+    api<K extends keyof C & string, TInputSchema extends z.ZodType = z.ZodType>(name: K & LambderMockEntryGuardsCheck<C, K, G, TDerived>, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived, TVocabulary, TCodesRequired>): LambderMockEntry<C, K>;
+    /** One of the module's endpoints deliberately left without a mock, as the app's notMocked() builds one; its restated guards may name the module's. */
+    notMocked<K extends keyof C & string>(name: K & LambderMockNotMockedGuardsCheck<C, K, G, TDerived>, input: LambderMockNotMockedInput<C, K, TDerived>): LambderMockEntry<C, K>;
+    /** The entries of one slice, keyed by name, as the app's apiSlice() gathers them. */
+    apiSlice<const E extends readonly LambderMockEntry<C, keyof C & string>[]>(...entries: E): LambderMockSlice<C, E[number]["name"]>;
+    /** Replaces one of the module's registered handlers until restored, as the app's override() does, its guardData typed with the module's guards. */
+    override<K extends keyof C & string>(name: K, handler: LambderMockHandler<C, K, S, G, TVocabulary, TCodesRequired>): LambderMockOverride;
+}
+export {};

package/dist/mock/LambderMockApiModule.js

@@ -0,0 +1,34 @@
+/**
+ * A part of a mock app with mock guards of its own: the app's entry builders,
+ * typed with the module's guards beside the app's. Made by the mock app's
+ * defineApiModule(); its entries are registered as any are (register,
+ * registerPartial), and registering them adds the module's guards to the
+ * app, refusing a name the app or another module declares. The mock twin of
+ * the server's LambderApiModule, so a module's mock guards are declared with
+ * the module's mocks, and the app's own setup imports none of them.
+ *
+ * `G` is the app's guards and the module's together, which is what the
+ * entries' handlers read guardData by.
+ */
+export class LambderMockApiModule {
+    door;
+    constructor(door) {
+        this.door = door;
+    }
+    /** A mock for one of the module's endpoints, as the app's api() builds one: its guards may be the app's and the module's own. */
+    api(name, entry) {
+        return this.door.api(name, entry);
+    }
+    /** One of the module's endpoints deliberately left without a mock, as the app's notMocked() builds one; its restated guards may name the module's. */
+    notMocked(name, input) {
+        return this.door.notMocked(name, input);
+    }
+    /** The entries of one slice, keyed by name, as the app's apiSlice() gathers them. */
+    apiSlice(...entries) {
+        return this.door.apiSlice(...entries);
+    }
+    /** Replaces one of the module's registered handlers until restored, as the app's override() does, its guardData typed with the module's guards. */
+    override(name, handler) {
+        return this.door.override(name, handler);
+    }
+}