lambder 15.0.2 → 16.0.1

package/dist/mock/LambderMockApp.d.ts

@@ -7,6 +7,8 @@ import { type LambderDeclaredVocabulary, type LambderHandlerRefusalsOf, type Lam
 import { type LambderApiTransport, type LambderApiTransportRequest } from "../shared/transport/LambderApiTransport.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { type LambderApiGuard } from "../api/LambderApiGuards.js";
+import type { LambderNoExtraKeys } from "../shared/util/LambderTypeUtilities.js";
+import { LambderMockApiModule, type LambderMockApiModuleChecks, type LambderMockApiModuleOptions } from "./LambderMockApiModule.js";
 import { LAMBDER_MOCK_ADAPTER_DOOR, type LambderMockAdapterDoor } from "./LambderMockAdapterDoor.js";
 import { LambderMemoryRateLimiter } from "../stores/LambderMemoryRateLimiter.js";
 import { LambderMemoryIdempotencyStore } from "../stores/LambderMemoryIdempotencyStore.js";
@@ -14,7 +16,7 @@ import { LambderMemorySessionStore } from "../stores/LambderMemorySessionStore.j
 import LambderSessionManager, { type LambderCreatedSession } from "../session/LambderSessionManager.js";
 import type { LambderMockAppOptions, LambderMockIdempotencyOptions, LambderMockTransport, LambderMockTransportOptions } from "./LambderMockCreateOptions.js";
 import type { LambderApiOptionEntry, LambderGuardDeclarationEntry } from "../shared/wire/LambderApiOptionEntries.js";
-import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, LambderMockEntryInput, LambderMockFailure, LambderMockFailureReason, LambderMockHandler, LambderMockLatency, LambderMockListener, LambderMockNotMockedInput, LambderMockRateLimitPolicies, LambderMockRegistryCheck, LambderMockRestEntry, LambderMockSessionCallContext, LambderMockSlice, LambderMockOverride, LambderMockRefusalsOf } from "./LambderMockTypes.js";
+import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, LambderMockEntryGuardsCheck, LambderMockEntryInput, LambderMockFailure, LambderMockFailureReason, LambderMockHandler, LambderMockLatency, LambderMockListener, LambderMockNotMockedGuardsCheck, LambderMockNotMockedInput, LambderMockRateLimitPolicies, LambderMockRegistryCheck, LambderMockRestEntry, LambderMockSessionCallContext, LambderMockSlice, LambderMockOverride, LambderMockRefusalsOf } from "./LambderMockTypes.js";
 /**
  * The mock runtime: the API core (LambderApiPipeline, the same class the
  * Lambda server runs) over memory stores, with typed mock handlers and mock
@@ -31,8 +33,10 @@ import type { LambderMockCallContext, LambderMockCallRecord, LambderMockEntry, L
  * generated `apiOptions` table, whose entries are their handlers alone.
  * `TVocabulary` and `TCodesRequired` are the refusal vocabulary the init
  * declared (declareRefusals), which types every handler's ctx.refuse.
+ * `D` is the generated guard declarations create() was given, which a
+ * module's mock guards are held to as create()'s are.
  */
-export declare class LambderMockApp<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> {
+export declare class LambderMockApp<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, D extends Record<string, LambderGuardDeclarationEntry> = {}> {
     readonly apiVersion: string | null;
     /** The memory stores, for assertions and reset; null for a subsystem that is off or backed by a store of yours. */
     readonly sessionStore: LambderMemorySessionStore<S> | null;
@@ -87,8 +91,8 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     private readonly apiOptions;
     /** The server's schemas, when create() was given the generated table: every entry's input is validated, and every answer parsed, through them. */
     private readonly apiSchemas;
-    /** The mock's own guards as create() was given them: which of them need a session, for an entry's mode without the apiOptions table. */
-    private readonly mockGuards;
+    /** The mock's own guards as create() was given them, and every registered module's beside them: which of them need a session, for an entry's mode without the apiOptions table. */
+    private mockGuards;
     /** The server's guard declarations, when create() was given the generated table: the refusal codes a declared guard adds to an entry. */
     private readonly guardDeclarations;
     /** The server's refusal vocabulary, when create() was given the generated table: whether each code an entry may refuse with carries data. */
@@ -100,6 +104,15 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
     constructor(options: LambderMockAppOptions<C, S, G, LambderMockRateLimitPolicies<S>, boolean | LambderMockIdempotencyOptions<S>, {}, Record<string, LambderApiOptionEntry> | undefined>, 
     /** The vocabulary the init declared, or null: what initLambderMock().declareRefusals() passes on. */
     declared?: LambderDeclaredVocabulary<TVocabulary, TCodesRequired> | null);
+    /**
+     * A mock guard stands in for the server's guard of its name, so it
+     * declares the codes that guard declares: its own refusals type its
+     * ctx.refuse and are what checkApiRefusals holds it to. The compiler
+     * compares literal lists at the guards option and at a module's; this
+     * catches a list typed as any string and a caller the compiler did not
+     * see.
+     */
+    private assertGuardRefusalsAgree;
     /**
      * The registration-time checks every entry goes through, mocked or not:
      * the ones the server runs on a definition, and the mock's own "a session
@@ -145,6 +158,11 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * and defaulted as on the server). Either alone where only one is given.
      */
     private entryInputOf;
+    /**
+     * An entry built and checked, by the app's api() or by a module's, whose
+     * declarations (`module`) its guards may name beside the app's own; the
+     * entry carries the module, which registering it adds.
+     */
     private buildEntry;
     /**
      * A mock for an endpoint: a handler, or the handler with the endpoint's
@@ -152,7 +170,7 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * session endpoint's session is fetched before the handler runs, and a
      * call without one is refused as on the server.
      */
-    api<K extends keyof C & string, TInputSchema extends z.ZodType = z.ZodType>(name: K, entry: LambderMockEntryInput<C, K, S, G, TInputSchema, TDerived, TVocabulary, TCodesRequired>): LambderMockEntry<C, K>;
+    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>;
     /**
      * An endpoint deliberately left without a mock; a call answers the
      * notMocked refusal carrying the reason. The refusal runs through the
@@ -162,7 +180,9 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * apiOptions table a session endpoint restates its guards to say so,
      * `notMocked(name, { reason, guards })`; no guard runs.
      */
-    notMocked<K extends keyof C & string>(name: K, input: LambderMockNotMockedInput<C, K, TDerived>): LambderMockEntry<C, K>;
+    notMocked<K extends keyof C & string>(name: K & LambderMockNotMockedGuardsCheck<C, K, G, TDerived>, input: LambderMockNotMockedInput<C, K, TDerived>): LambderMockEntry<C, K>;
+    /** A notMocked entry, by the app's notMocked() or by a module's, whose guards give its mode beside the app's own. */
+    private buildNotMockedEntry;
     /**
      * "Everything I did not register is not mocked, for this reason", as an
      * argument to the same register() call:
@@ -190,8 +210,33 @@ export declare class LambderMockApp<C extends LambderApiContractShape, S = any,
      * a test cares about that path.
      */
     restNotMocked(reason: string): LambderMockRestEntry;
+    /**
+     * Defines a module: the mock guards a part of the app declares with its
+     * own entries, standing in for the guards the server's module declares
+     * (its defineApiModule). Returns the module's entry builders, whose
+     * entries may name the app's guards and the module's own; registering
+     * them adds the module's guards to the app. So the app's create() need
+     * not import every module's mock guards.
+     *
+     * ```ts
+     * export const giftCardMocks = mockApp.defineApiModule({ guards: { cardHolder: mock.guard({ ... }) } });
+     * giftCardMocks.apiSlice(giftCardMocks.api("giftCards.redeem", async () => ({ redeemed: true })));
+     * ```
+     *
+     * Each guard is held to what create()'s are held to (the contract, the
+     * generated guardDeclarations, surplus keys); a name the app's create()
+     * declares is refused here, at compile time and at the call, and a name
+     * two modules declare when the second is registered.
+     */
+    defineApiModule<const TOptions extends LambderMockApiModuleOptions<S>>(options: LambderNoExtraKeys<TOptions, LambderMockApiModuleOptions<S>> & LambderMockApiModuleChecks<C, S, G, D, TOptions>): LambderMockApiModule<C, S, G & TOptions["guards"], TDerived, TVocabulary, TCodesRequired>;
     /** The entries of one module as a slice, keyed by name. Two entries for one endpoint is an error here. */
     apiSlice<const E extends readonly LambderMockEntry<C, keyof C & string>[]>(...entries: E): LambderMockSlice<C, E[number]["name"]>;
+    /**
+     * Registers slices, adding the modules their entries were built with: a
+     * module's mock guards are checked against the app's and every other
+     * module's first, and taken only once the registry took the slices, so a
+     * refused registration leaves the app as it was.
+     */
     private addSlices;
     /**
      * Registers the whole contract: every endpoint in exactly one slice, or
@@ -389,7 +434,7 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
          * dropped. `I` exists for the same reason `P` does, and
          * LambderMockSurplusKeys puts the error back on the key.
          */
-        create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, LambderMergedRefusalVocabulary<TVocabulary>, TRequireCodes>;
+        create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, LambderMergedRefusalVocabulary<TVocabulary>, TRequireCodes, D>;
     };
     /**
      * Builds a mock guard: the server guard's shape, the handler seeing the
@@ -425,5 +470,5 @@ export declare const initLambderMock: <C extends LambderApiContractShape, S = an
      * dropped. `I` exists for the same reason `P` does, and
      * LambderMockSurplusKeys puts the error back on the key.
      */
-    create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, never, false>;
+    create<const G extends Record<string, LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>> = {}, const P extends LambderMockRateLimitPolicies<S> = {}, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>, const D extends Record<string, LambderGuardDeclarationEntry> = {}, const A extends Record<string, LambderApiOptionEntry> | undefined = undefined>(options: LambderMockAppOptions<C, S, G, P, I, D, A>): LambderMockApp<C, S, G, [A] extends [undefined] ? false : true, never, false, D>;
 };

package/dist/mock/LambderMockApp.js

@@ -15,6 +15,8 @@ import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { serializeClearCookie } from "../shared/wire/LambderCookie.js";
 import { LOOPBACK_CLIENT_IP, normalizeClientIp } from "../shared/util/LambderClientIp.js";
 import { lambderGuardBuilder, toGuardEntries } from "../api/LambderApiGuards.js";
+import { apiModuleDeclarationsOf } from "../api/LambderApiModules.js";
+import { LambderMockApiModule } from "./LambderMockApiModule.js";
 import { lambderRateLimitKeyBuilder } from "../api/LambderApiRateLimits.js";
 import { LambderMockFailureInjector, LambderMockTransportError } from "./LambderMockFailureInjector.js";
 import { LambderMockCallRecorder } from "./LambderMockCallRecorder.js";
@@ -58,6 +60,8 @@ const defaultCookieHost = () => globalThis.location?.host || "localhost";
  * generated `apiOptions` table, whose entries are their handlers alone.
  * `TVocabulary` and `TCodesRequired` are the refusal vocabulary the init
  * declared (declareRefusals), which types every handler's ctx.refuse.
+ * `D` is the generated guard declarations create() was given, which a
+ * module's mock guards are held to as create()'s are.
  */
 export class LambderMockApp {
     apiVersion;
@@ -122,7 +126,7 @@ export class LambderMockApp {
     apiOptions;
     /** The server's schemas, when create() was given the generated table: every entry's input is validated, and every answer parsed, through them. */
     apiSchemas;
-    /** The mock's own guards as create() was given them: which of them need a session, for an entry's mode without the apiOptions table. */
+    /** The mock's own guards as create() was given them, and every registered module's beside them: which of them need a session, for an entry's mode without the apiOptions table. */
     mockGuards;
     /** The server's guard declarations, when create() was given the generated table: the refusal codes a declared guard adds to an entry. */
     guardDeclarations;
@@ -138,23 +142,9 @@ export class LambderMockApp {
         this.apiVersion = options.apiVersion ?? null;
         this.apiOptions = options.apiOptions ?? null;
         this.apiSchemas = options.apiSchemas ? new LambderMockApiSchemas(options.apiSchemas) : null;
-        this.mockGuards = options.guards ?? null;
+        this.mockGuards = { ...options.guards };
         this.guardDeclarations = options.guardDeclarations ?? null;
-        // A mock guard stands in for the server's guard of its name, so it
-        // declares the codes that guard declares: its own refusals type its
-        // ctx.refuse and are what checkApiRefusals holds it to. The compiler
-        // compares literal lists at the guards option; this catches a list
-        // typed as any string and a caller the compiler did not see.
-        for (const [name, guard] of Object.entries(options.guards ?? {})) {
-            if (!this.guardDeclarations || !Object.prototype.hasOwnProperty.call(this.guardDeclarations, name))
-                continue;
-            const own = new Set(Array.isArray(guard?.refusals) ? guard.refusals : []);
-            const declared = new Set(this.guardDeclarations[name].refusals ?? []);
-            if (own.size !== declared.size || [...declared].some((code) => !own.has(code))) {
-                const listed = (codes) => codes.size ? [...codes].map((code) => `"${code}"`).join(", ") : "none";
-                throw new Error(`LambderMockApp: the mock guard "${name}" declares the refusals ${listed(own)}, and the server's guard of that name declares ${listed(declared)} in the guardDeclarations table. A mock guard declares exactly the server guard's codes: regenerate the table, or give the mock guard refusals: [${[...declared].map((code) => `"${code}"`).join(", ")}].`);
-            }
-        }
+        this.assertGuardRefusalsAgree(options.guards ?? {});
         this.refusalVocabulary = declared?.vocabulary ?? null;
         this.requireRefusalCodes = declared?.requireCodes ?? false;
         if (this.requireRefusalCodes && !this.apiOptions) {
@@ -253,6 +243,26 @@ export class LambderMockApp {
             atRestSecret: sessionOptions ? sessionOptions.sessionSalt ?? DEFAULT_MOCK_SESSION_SALT : undefined,
         });
     }
+    /**
+     * A mock guard stands in for the server's guard of its name, so it
+     * declares the codes that guard declares: its own refusals type its
+     * ctx.refuse and are what checkApiRefusals holds it to. The compiler
+     * compares literal lists at the guards option and at a module's; this
+     * catches a list typed as any string and a caller the compiler did not
+     * see.
+     */
+    assertGuardRefusalsAgree(guards) {
+        for (const [name, guard] of Object.entries(guards)) {
+            if (!this.guardDeclarations || !Object.prototype.hasOwnProperty.call(this.guardDeclarations, name))
+                continue;
+            const own = new Set(Array.isArray(guard?.refusals) ? guard.refusals : []);
+            const declared = new Set(this.guardDeclarations[name].refusals ?? []);
+            if (own.size !== declared.size || [...declared].some((code) => !own.has(code))) {
+                const listed = (codes) => codes.size ? [...codes].map((code) => `"${code}"`).join(", ") : "none";
+                throw new Error(`LambderMockApp: the mock guard "${name}" declares the refusals ${listed(own)}, and the server's guard of that name declares ${listed(declared)} in the guardDeclarations table. A mock guard declares exactly the server guard's codes: regenerate the table, or give the mock guard refusals: [${[...declared].map((code) => `"${code}"`).join(", ")}].`);
+            }
+        }
+    }
     // -----------------------------------------------------------------------
     // Registry
     // -----------------------------------------------------------------------
@@ -266,8 +276,8 @@ export class LambderMockApp {
      * silently and answer its first call with a 500 naming the SERVER's
      * option, for a mistake fixed by one option at create().
      */
-    assertEntryRegistration(definition) {
-        this.pipeline.assertRegistration(definition);
+    assertEntryRegistration(definition, module) {
+        this.pipeline.assertRegistration(definition, module ?? undefined);
         if (definition.mode === "session" && !this.pipeline.hasSessions) {
             throw new Error(`LambderMockApp: session endpoint "${definition.name}" needs the sessions option at creation.`);
         }
@@ -294,11 +304,12 @@ export class LambderMockApp {
      * otherwise the ones the entry restates, each read off the guardDeclarations
      * table or the mock's own guards.
      */
-    modeOf(declared, restatedGuards) {
+    modeOf(declared, restatedGuards, module) {
         if (declared)
             return declared.mode;
         const needsSession = (guard) => (this.guardDeclarations && Object.prototype.hasOwnProperty.call(this.guardDeclarations, guard) && this.guardDeclarations[guard].session === true)
-            || (this.mockGuards && Object.prototype.hasOwnProperty.call(this.mockGuards, guard) && this.mockGuards[guard].session === true);
+            || (Object.prototype.hasOwnProperty.call(this.mockGuards, guard) && this.mockGuards[guard].session === true)
+            || (module !== null && Object.prototype.hasOwnProperty.call(module.guards, guard) && module.guards[guard].session === true);
         return toGuardEntries(restatedGuards).some(({ name: guard }) => needsSession(guard)) ? "session" : "public";
     }
     /**
@@ -352,10 +363,15 @@ export class LambderMockApp {
         const server = this.apiSchemas.inputOf(name);
         return own ? server.pipe(own) : server;
     }
-    buildEntry(name, input) {
+    /**
+     * An entry built and checked, by the app's api() or by a module's, whose
+     * declarations (`module`) its guards may name beside the app's own; the
+     * entry carries the module, which registering it adds.
+     */
+    buildEntry(name, input, module) {
         const options = (typeof input === "function" ? { handler: input } : input);
         const declared = this.declaredOptionsOf(name);
-        const mode = this.modeOf(declared, options.guards);
+        const mode = this.modeOf(declared, options.guards, module);
         if (declared) {
             // A caller the compiler did not see (a JavaScript slice, a cast)
             // would otherwise have its restatement silently lose to the table.
@@ -379,9 +395,10 @@ export class LambderMockApp {
             // undefined }`, a refusal a client cannot read.
             input: this.entryInputOf(name, options.input),
         };
-        this.assertEntryRegistration(definition);
+        this.assertEntryRegistration(definition, module);
         const handler = options.handler;
-        return { name, mode, definition, handler: async (ctx) => await handler(ctx), notMockedReason: null };
+        const entry = { name, mode, definition, handler: async (ctx) => await handler(ctx), notMockedReason: null };
+        return module ? { ...entry, module } : entry;
     }
     /**
      * A mock for an endpoint: a handler, or the handler with the endpoint's
@@ -390,7 +407,7 @@ export class LambderMockApp {
      * call without one is refused as on the server.
      */
     api(name, entry) {
-        return this.buildEntry(name, entry);
+        return this.buildEntry(name, entry, null);
     }
     /**
      * An endpoint deliberately left without a mock; a call answers the
@@ -402,14 +419,18 @@ export class LambderMockApp {
      * `notMocked(name, { reason, guards })`; no guard runs.
      */
     notMocked(name, input) {
+        return this.buildNotMockedEntry(name, input, null);
+    }
+    /** A notMocked entry, by the app's notMocked() or by a module's, whose guards give its mode beside the app's own. */
+    buildNotMockedEntry(name, input, module) {
         const { reason, guards } = (typeof input === "string" ? { reason: input } : input);
         const declared = this.declaredOptionsOf(name);
         if (declared && guards !== undefined) {
             throw new Error(`LambderMockApp: "${name}" restates its guards option, which the apiOptions table given to create() already declares. Leave it out of the entry.`);
         }
-        const mode = this.modeOf(declared, guards);
+        const mode = this.modeOf(declared, guards, module);
         const definition = { name, mode };
-        this.assertEntryRegistration(definition);
+        this.assertEntryRegistration(definition, module);
         return { name, mode, definition, handler: null, notMockedReason: reason };
     }
     /**
@@ -441,6 +462,42 @@ export class LambderMockApp {
     restNotMocked(reason) {
         return { restNotMockedReason: reason };
     }
+    /**
+     * Defines a module: the mock guards a part of the app declares with its
+     * own entries, standing in for the guards the server's module declares
+     * (its defineApiModule). Returns the module's entry builders, whose
+     * entries may name the app's guards and the module's own; registering
+     * them adds the module's guards to the app. So the app's create() need
+     * not import every module's mock guards.
+     *
+     * ```ts
+     * export const giftCardMocks = mockApp.defineApiModule({ guards: { cardHolder: mock.guard({ ... }) } });
+     * giftCardMocks.apiSlice(giftCardMocks.api("giftCards.redeem", async () => ({ redeemed: true })));
+     * ```
+     *
+     * Each guard is held to what create()'s are held to (the contract, the
+     * generated guardDeclarations, surplus keys); a name the app's create()
+     * declares is refused here, at compile time and at the call, and a name
+     * two modules declare when the second is registered.
+     */
+    defineApiModule(options) {
+        const given = options;
+        if (given.rateLimitPolicies !== undefined) {
+            throw new Error("LambderMockApp: defineApiModule() takes guards alone. A mock takes every rate-limit policy at create(), the modules' among them, from the generated table (lambderMockPoliciesFrom).");
+        }
+        const declarations = apiModuleDeclarationsOf({ guards: given.guards }, "LambderMockApp");
+        this.assertGuardRefusalsAgree(declarations.guards);
+        // Checked against the app now, so a name its create() declares fails
+        // where the module is defined; registration checks again, against
+        // the other modules.
+        this.pipeline.modulesToAdd([{ module: declarations, usedBy: "being defined" }]);
+        return new LambderMockApiModule({
+            api: (name, entry) => this.buildEntry(name, entry, declarations),
+            notMocked: (name, input) => this.buildNotMockedEntry(name, input, declarations),
+            apiSlice: (...entries) => this.apiSlice(...entries),
+            override: (name, handler) => this.override(name, handler),
+        });
+    }
     /** The entries of one module as a slice, keyed by name. Two entries for one endpoint is an error here. */
     apiSlice(...entries) {
         const slice = {};
@@ -451,8 +508,27 @@ export class LambderMockApp {
         }
         return slice;
     }
+    /**
+     * Registers slices, adding the modules their entries were built with: a
+     * module's mock guards are checked against the app's and every other
+     * module's first, and taken only once the registry took the slices, so a
+     * refused registration leaves the app as it was.
+     */
     addSlices(slices) {
+        const uses = [];
+        for (const slice of slices) {
+            if ("restNotMockedReason" in slice && typeof slice.restNotMockedReason === "string")
+                continue;
+            for (const entry of Object.values(slice)) {
+                const module = entry?.module;
+                if (module && !uses.some((use) => use.module === module))
+                    uses.push({ module, usedBy: `building the entry of "${entry.name}"` });
+            }
+        }
+        const added = this.pipeline.modulesToAdd(uses);
         this.registry.addSlices(slices);
+        this.pipeline.addModules(added);
+        this.mockGuards = { ...this.mockGuards, ...added.guards };
     }
     /**
      * Registers the whole contract: every endpoint in exactly one slice, or

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -2,8 +2,8 @@ import type { z } from "zod";
 import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignatureMap.js";
 import type { LambderApiRefusalConfig } from "../shared/wire/LambderApiContract.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
-import type { MaybePromise } from "../shared/util/LambderTypeUtilities.js";
-import type { LambderContractGuardNames, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitNames, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
+import type { LambderMaybePromise } from "../shared/util/LambderTypeUtilities.js";
+import type { LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitNames, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard } from "../api/LambderApiGuards.js";
 import type { LambderApiOptionEntry, LambderGuardDeclarationEntry } from "../shared/wire/LambderApiOptionEntries.js";
 import type { LambderApiSchemaEntry } from "../shared/wire/LambderApiSchemaEntries.js";
@@ -17,7 +17,7 @@ import type { LambderSessionStore } from "../shared/contracts/LambderSessionStor
 import type { LambderSessionDataOptions } from "../session/LambderSessionManager.js";
 import type { LambderSessionCookieOptions } from "../session/LambderSessionController.js";
 import type { LambderSessionCrypto } from "../session/LambderSessionCrypto.js";
-import type { LambderMockCallContext, LambderMockGuards, LambderMockLatency, LambderMockRateLimitPolicies, LambderMockSessionCallContext, LambderMockSessionGuardsCheck, LambderMockSurplusKeys } from "./LambderMockTypes.js";
+import type { LambderMockCallContext, LambderMockGuardMapChecks, LambderMockLatency, LambderMockRateLimitPolicies, LambderMockSessionCallContext, LambderMockSurplusKeys } from "./LambderMockTypes.js";
 export type LambderMockSessionsOptions<S> = {
     /** Where the mock's sessions rest. Default: a fresh LambderMemorySessionStore. */
     store?: LambderSessionStore<S>;
@@ -162,24 +162,24 @@ type LambderMockGuardRefusalsMismatch<TDeclaration> = {
     } ? R : readonly [];
 };
 /** Each mock guard the declarations know held to its declared shape and refusal codes; a guard the table does not have is free. */
-type LambderMockGuardsAgree<G, D> = {
+export type LambderMockGuardsAgree<G, D> = {
     [N in keyof G & keyof D]: (G[N] extends LambderMockGuardShapeOf<D[N]> ? unknown : LambderMockGuardShapeOf<D[N]>) & LambderMockGuardRefusalsAgree<G[N], D[N]>;
 };
 /**
- * The guards option: required whenever the contract declares any guard name,
- * omittable only for a contract that declares none.
+ * The guards option: the app's own mock guards, each held to what the
+ * contract asks of a guard of its name (LambderMockGuardMapChecks), to the
+ * generated declarations when they are given, and to the mock contexts.
  *
- * The same reasoning the entry's own guards field carries: a guard the mock
- * does not declare cannot run, so a call the server answers notAuthorized
- * would answer 200 here. Optional, it would be the droppable half of exactly
- * the check it exists for.
+ * It need not name every guard the contract declares, since a part of the
+ * app may declare its own with its entries (defineApiModule); what it may
+ * not do is leave one out that an entry needs. Every entry is held to having
+ * a mock guard for each guard its endpoint declares, in the map it is built
+ * with (LambderMockEntryGuardsCheck), because a guard the mock does not
+ * declare cannot run, and a call the server answers notAuthorized would
+ * answer 200 here.
  */
-type LambderMockGuardsOption<C, S, G, D> = [
-    LambderContractGuardNames<C>
-] extends [never] ? {
-    guards?: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>> & LambderMockSessionGuardsCheck<C, G>;
-} : {
-    guards: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>> & LambderMockSessionGuardsCheck<C, G>;
+type LambderMockGuardsOption<C, S, G, D> = {
+    guards?: G & LambderMockGuardMapChecks<C, S, G> & LambderMockGuardShapes<S, G> & LambderMockGuardsAgree<G, NoInfer<D>>;
 };
 /**
  * The sessions, idempotency and rateLimits options: each required whenever
@@ -216,7 +216,7 @@ type LambderMockRateLimitsOption<C, S, P extends LambderMockRateLimitPolicies<S>
     rateLimits: LambderMockRateLimitsOptions<C, S, P>;
 };
 /** Each guard checked for surplus keys, so `sesion: true` on an inline guard is an error at the key rather than a guard that silently runs as public. */
-type LambderMockGuardShapes<S, G> = {
+export type LambderMockGuardShapes<S, G> = {
     [N in keyof G]: LambderMockSurplusKeys<G[N], LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>>;
 };
 /**
@@ -323,7 +323,7 @@ export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicie
      * data. Return null for the standard 422 `validation` refusal, which is
      * also what an app that sets neither gets.
      */
-    onInvalidInput?: (zodError: z.ZodError, ctx: LambderMockCallContext<S>) => MaybePromise<LambderMockInvalidInputAnswer | null>;
+    onInvalidInput?: (zodError: z.ZodError, ctx: LambderMockCallContext<S>) => LambderMaybePromise<LambderMockInvalidInputAnswer | null>;
 };
 /**
  * What the server's input validation handler answers, as a mock states it:

package/dist/mock/LambderMockTypes.d.ts

@@ -6,7 +6,7 @@
  * the contract stays a type-only import in the consuming app.
  */
 import type { z } from "zod";
-import type { LambderApiMode, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractGuardInputsOf, LambderContractGuardNames, LambderContractGuardsOf, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitOf, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
+import type { LambderApiMode, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractGuardInputsOf, LambderContractGuardNames, LambderContractGuardsOf, LambderContractIdempotencyOf, LambderContractMode, LambderContractRateLimitOf, LambderGuardNamesIn } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard, LambderGuardDataOf, LambderGuardMetaMap } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck } from "../api/LambderApiRateLimits.js";
 import type { LambderApiCallContext, LambderResponseTools } from "../api/LambderApiCallContext.js";
@@ -20,6 +20,7 @@ import type { LambderContractRefusalsOf } from "../shared/wire/LambderApiContrac
 import type { LambderHandlerRefusalsOf } from "../api/LambderApiRefusals.js";
 import type { LambderSessionRecord } from "../shared/contracts/LambderSessionStore.js";
 import type LambderSessionController from "../session/LambderSessionController.js";
+import type { LambderApiModuleDeclarations } from "../api/LambderApiModules.js";
 export type LambderMockInputOf<C, K extends keyof C> = C[K] extends {
     input: infer I;
 } ? I : never;
@@ -101,13 +102,13 @@ export type LambderMockContext<C, K extends keyof C, S, G, TVocabulary = never,
     refuse: LambderDeclaredRefuse<LambderMockRefusalsOf<C, K, TVocabulary>, TCodesRequired>;
 };
 /**
- * The guard map a mock app must declare: one guard per name any endpoint of
- * the contract declares, plus, for each guardInput-mode guard, a `guardInput`
- * schema whose input is what the contract says a client sends. A guard a
- * public endpoint names may not require a session. A missing name, a schema
- * that parses to something else, or a public endpoint's guard that requires
- * a session fails at the `guards` option; LambderMockSessionGuardsCheck
- * holds the session endpoints to the same rule from the other side.
+ * What the contract asks of a mock guard of each name it declares: the mock
+ * call contexts, plus, for each guardInput-mode guard, a `guardInput` schema
+ * whose input is what the contract says a client sends, and, for a guard a
+ * public endpoint names, no session. LambderMockGuardMapChecks holds a mock
+ * guard map (create()'s, or a module's) to it, name by name; an entry is held
+ * to having a mock guard for every guard its endpoint declares
+ * (LambderMockEntryGuardsCheck).
  */
 export type LambderMockGuards<C, S = any> = {
     [N in LambderContractGuardNames<C>]: LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;
@@ -120,33 +121,50 @@ export type LambderMockGuards<C, S = any> = {
         session?: false;
     };
 };
+/**
+ * A mock guard map held, guard by guard, to what the contract asks of the
+ * guards it names (LambderMockGuards): a schema that parses to something
+ * else, or a public endpoint's guard that requires a session, fails at the
+ * map. Guards the contract does not declare are free.
+ */
+export type LambderMockGuardMapChecks<C, S, G> = {
+    [N in keyof G & keyof LambderMockGuards<C, S>]: LambderMockGuards<C, S>[N];
+};
 /** The guards of a mock guard map that need a session. */
 type LambderMockSessionGuardNames<G> = {
     [N in keyof G]: G[N] extends {
         session: true;
     } ? N : never;
 }[keyof G];
-/** The contract's session endpoints none of whose guards the mock guard map declares `session: true`. */
-type LambderMockSessionEndpointsWithoutSessionGuard<C, G> = {
-    [K in LambderContractKeysWithMode<C, "session">]: [
-        Extract<LambderGuardNamesIn<LambderContractGuardsOf<C, K>>, LambderMockSessionGuardNames<G>>
-    ] extends [never] ? K : never;
-}[LambderContractKeysWithMode<C, "session">];
+/** The guards endpoint K declares that the guard map an entry for it is built with has no mock guard for. */
+type LambderMockGuardsMissing<C, K extends keyof C, G> = Exclude<LambderGuardNamesIn<LambderContractGuardsOf<C, K>>, keyof G>;
+/**
+ * Whether an entry for session endpoint K would run as public: without the
+ * apiOptions table (`TDerived`) the mock reads an entry's mode off the guards
+ * it restates, and none of those the map declares says `session: true`.
+ */
+type LambderMockRunsAsPublic<C, K extends keyof C, G, TDerived extends boolean> = TDerived extends true ? false : LambderContractMode<C, K> extends "session" ? ([Extract<LambderGuardNamesIn<LambderContractGuardsOf<C, K>>, LambderMockSessionGuardNames<G>>] extends [never] ? true : false) : false;
+/** The error an entry that would run as public meets on its name. */
+type LambderMockRunsAsPublicError<K> = {
+    readonly "lambder: this session endpoint names no mock guard declared session: true, so the mock would run it as public": K;
+};
 /**
- * The mock guard map held to the server's rule for session endpoints: each
- * names at least one guard that needs a session. The guards are what make
- * an endpoint a session one, on the server and in the mock alike, and
- * without the apiOptions table the mock reads an entry's mode off the guards
- * it restates, so a session endpoint none of whose mock guards says
- * `session: true` would run as public: a signed-out call would reach a
- * handler typed with its session present. The property name is the message
- * and its value the endpoints at fault.
+ * An entry held to the guard map it is built with (create()'s, or a
+ * module's beside it): each guard its endpoint declares has a mock guard
+ * there, since a guard the mock does not declare cannot run and the mock
+ * would answer 200 where the server answers notAuthorized; and, where the
+ * mock reads the entry's mode off its guards, a session endpoint names one
+ * that needs a session, or a signed-out call would reach a handler typed
+ * with its session present. Intersected onto the entry's name: the property
+ * name is the message, its value the guards or the endpoint at fault.
  */
-export type LambderMockSessionGuardsCheck<C, G> = [
-    LambderMockSessionEndpointsWithoutSessionGuard<C, G>
-] extends [never] ? unknown : {
-    readonly "lambder: these session endpoints name no mock guard declared session: true, so the mock would run them as public": LambderMockSessionEndpointsWithoutSessionGuard<C, G>;
+export type LambderMockEntryGuardsCheck<C, K extends keyof C, G, TDerived extends boolean> = [
+    LambderMockGuardsMissing<C, K, G>
+] extends [never] ? (LambderMockRunsAsPublic<C, K, G, TDerived> extends true ? LambderMockRunsAsPublicError<K> : unknown) : {
+    readonly "lambder: these guards of this endpoint have no mock guard where its entry is built; declare them at create(), or build the entry with the defineApiModule() that declares them": LambderMockGuardsMissing<C, K, G>;
 };
+/** A notMocked entry runs no guard, so it is held only to the mode its restated guards give it (see LambderMockEntryGuardsCheck). */
+export type LambderMockNotMockedGuardsCheck<C, K extends keyof C, G, TDerived extends boolean> = LambderMockRunsAsPublic<C, K, G, TDerived> extends true ? LambderMockRunsAsPublicError<K> : unknown;
 export type LambderMockHandler<C, K extends keyof C, S, G, TVocabulary = never, TCodesRequired extends boolean = false> = (ctx: LambderMockContext<C, K, S, G, TVocabulary, TCodesRequired>) => LambderMockOutputOf<C, K> | Promise<LambderMockOutputOf<C, K>>;
 /**
  * The guards field of an entry: required whenever the contract declares any
@@ -288,6 +306,8 @@ export type LambderMockEntry<C, K extends keyof C & string> = {
     readonly definition: LambderApiDefinition;
     readonly handler: ((ctx: any) => Promise<unknown>) | null;
     readonly notMockedReason: string | null;
+    /** The module whose builders made the entry (defineApiModule), whose mock guards registering it adds; absent on the app's own. */
+    readonly module?: LambderApiModuleDeclarations;
 };
 /** A slice: the entries of one module, keyed by endpoint name. */
 export type LambderMockSlice<C, K extends keyof C & string> = {

package/dist/mock.d.ts

@@ -7,9 +7,11 @@
  * production bundle by construction: nothing else imports it.
  */
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
+export { LambderMockApiModule } from "./mock/LambderMockApiModule.js";
+export type { LambderMockApiModuleOptions, LambderMockApiModuleChecks, LambderMockApiModuleDoor } from "./mock/LambderMockApiModule.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockInvalidInputAnswer, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
-export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockNotMockedInput, LambderMockSessionGuardsCheck, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
+export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockNotMockedInput, LambderMockEntryGuardsCheck, LambderMockNotMockedGuardsCheck, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
 export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderCustomKeyedPolicyNames, LambderMockPolicyKeys } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderMockGuardShapeOf } from "./mock/LambderMockCreateOptions.js";
@@ -34,6 +36,7 @@ export type { LambderSessionCrypto } from "./session/LambderSessionCrypto.js";
 export { LambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderRefusalMessage, LambderDeclaredRefuse, LambderDeclaredRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
 export { LambderApiRefusalValidationError } from "./api/LambderApiRefusals.js";
+export type { LambderRefusalVocabularyOption, LambderRefusalVocabularyOptionChecks } from "./api/LambderApiRefusals.js";
 export { assertApiSuccess, assertApiFailure, assertApiRefusal } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderExpectedFailure } from "./shared/wire/LambderOutcomeAssertions.js";
 export type { LambderApiRequest } from "./api/LambderApiRequest.js";

package/dist/mock.js

@@ -7,6 +7,8 @@
  * production bundle by construction: nothing else imports it.
  */
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
+// A part of the mock app with mock guards of its own, declared with its entries.
+export { LambderMockApiModule } from "./mock/LambderMockApiModule.js";
 // The four collaborators behind LambderMockApp (the entry registry, the call
 // recorder, the failure injector, the browser cookies) are deliberately not
 // exported: the runtime is reached through the app. Only the error a

package/dist/shared/util/LambderTypeUtilities.d.ts

@@ -11,7 +11,7 @@
  * writes the synchronous form when it has nothing to await, and the framework
  * awaits either.
  */
-export type MaybePromise<T> = T | Promise<T>;
+export type LambderMaybePromise<T> = T | Promise<T>;
 /**
  * T with every object and array readonly, all the way down: what an API
  * handler's returned answer is checked against.