lambder 15.1.1 → 16.0.1

package/dist/core/Lambder.js

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

package/dist/core/LambderApiBuilders.d.ts

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

package/dist/core/LambderApiBuilders.js

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

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;
+    }
+}