lambder 7.2.3 → 7.2.5

package/CHANGELOG.md

@@ -9,6 +9,35 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [7.2.4] - 2026-09-19
+
+### Changed
+
+- **The mock's options are checked against the contract at compile time.**
+  Only the guard map was before, so a mock whose other options no longer fit
+  the contract compiled and then threw when its registry loaded, which in a
+  dev server is a blank page and an error in the browser console. Now each of
+  these is a type error at `create()`:
+  - `rateLimits.policies` leaving out a policy an endpoint references (a
+    policy added on the server and not to the mock);
+  - `sessions`, `idempotency` or `rateLimits` left out (or switched off)
+    while the contract has an endpoint that needs it, the way `guards`
+    already was;
+  - a guard with `session: true`, or a policy keyed `per: "session"`, where a
+    public endpoint names it;
+  - a `perPolicy` budget on a policy whose windows an endpoint overrides.
+
+  Each of these was already refused at registration, so a mock that compiles
+  now behaves as it did. The runtime checks stay for callers the types do not
+  reach.
+
+### Added
+
+- **`LambderContractRateLimitNames<C, M?>`**, from both entries: every
+  rate-limit policy name the contract references, the twin of
+  `LambderContractGuardNames`. Both now take an optional mode to read only the
+  public or only the session endpoints.
+
 ## [7.2.3] - 2026-09-19
 
 ### Added

package/dist/client.d.ts

@@ -23,7 +23,7 @@ export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallF
 export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, LambderLogListHandler, } from "./client/LambderCaller.js";
 export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderAppRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
 export { compressPayloadGzip, isRequestCompressionAvailable, COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, } from "./shared/wire/LambderRequestPayload.js";

package/dist/core/Lambder.d.ts

@@ -60,10 +60,17 @@ export default class Lambder<TSessionData = any, _TContract extends Record<strin
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
      *
+     * Export it as an interface extending LambderFlattenContract, not as a
+     * type alias. Chaining builds the contract as an intersection one member
+     * deep per endpoint, and an interface collapses that into one declared
+     * set of members, which every generic read of the contract (a mock
+     * registry, a needs map, the typed caller) is then far cheaper against.
+     * See LambderFlattenContract for the measurements.
+     *
      * @example
      * ```typescript
      * const lambder = new Lambder().addApi(...).addApi(...);
-     * export type ApiContractType = typeof lambder.ApiContract;
+     * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
      * ```
      */
     readonly ApiContract: _TContract;

package/dist/core/Lambder.js

@@ -55,10 +55,17 @@ export default class Lambder {
      * Type property for extracting the API contract
      * Use this to export your API types to the frontend
      *
+     * Export it as an interface extending LambderFlattenContract, not as a
+     * type alias. Chaining builds the contract as an intersection one member
+     * deep per endpoint, and an interface collapses that into one declared
+     * set of members, which every generic read of the contract (a mock
+     * registry, a needs map, the typed caller) is then far cheaper against.
+     * See LambderFlattenContract for the measurements.
+     *
      * @example
      * ```typescript
      * const lambder = new Lambder().addApi(...).addApi(...);
-     * export type ApiContractType = typeof lambder.ApiContract;
+     * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
      * ```
      */
     ApiContract;

package/dist/index.d.ts

@@ -104,7 +104,7 @@ export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js
 export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderFlattenContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";

package/dist/mock/LambderMockCreateOptions.d.ts

@@ -1,12 +1,12 @@
 import type { LambderApiSignatureMap } from "../shared/wire/LambderApiSignature.js";
-import type { LambderContractGuardNames } from "../shared/wire/LambderApiContract.js";
+import type { LambderContractGuardNames, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractRateLimitNames, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard } from "../api/LambderApiGuards.js";
 import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
 import type { LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderApiTransport } from "../shared/transport/LambderApiTransport.js";
 import type { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
-import type { LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import type { LambderRateLimiter, LambderRateLimitWindow } from "../shared/contracts/LambderRateLimiter.js";
 import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
 import type { LambderSessionDataRefreshConfig } from "../session/LambderSessionManager.js";
 import type { LambderSessionCookieOptions } from "../session/LambderSessionController.js";
@@ -60,19 +60,52 @@ export type LambderMockIdempotencyOptions<S = any> = {
      */
     callerIdentity?: (ctx: Omit<LambderMockCallContext<S>, "session">, request: LambderApiRequest) => string | null | Promise<string | null>;
 };
+/** Policy names whose windows some endpoint of the contract overrides, in the map form of its rateLimit option. */
+type LambderContractWindowOverrideNames<C> = {
+    [K in keyof C]: LambderWindowOverrideNamesIn<LambderContractRateLimitOf<C, K>>;
+}[keyof C] & string;
+type LambderWindowOverrideNamesIn<R> = R extends string | readonly string[] ? never : {
+    [N in keyof R]: R[N] extends object ? ([Extract<keyof R[N], LambderRateLimitWindow>] extends [never] ? never : N) : never;
+}[keyof R];
+/** Endpoint names whose idempotency option asks for a store (`false` is an opt-out and asks for none). */
+type LambderContractIdempotentKeys<C> = {
+    [K in keyof C]: [LambderContractIdempotencyOf<C, K>] extends [never] ? never : LambderContractIdempotencyOf<C, K> extends false ? never : K;
+}[keyof C];
 /**
  * The rate limits option: the policies endpoints may restate, the limiter
  * they are counted on, and what happens when that limiter throws.
  *
+ * The policies are held to what the server's own policies were held to when
+ * it registered the same endpoints, because an entry the mock's copy does not
+ * fit cannot be registered, and this makes that an error at the option rather
+ * than a throw when the registry loads. So the map names every policy the
+ * contract references, a policy a public endpoint names is not keyed per
+ * session, and a policy whose windows an endpoint overrides keeps a per-API
+ * budget. Policies the contract does not reference may be added freely.
+ *
  * `failOpen` is the server's own option (see LambderApiRateLimitsConfig) and
  * is here for the reason the idempotency option's twin is: with a limiter of
  * the app's own that fails, a mock that cannot express it always lets the
  * call through, so it answers 200 where a server configured to refuse answers
  * 429.
  */
-type LambderMockRateLimitsOptions<S, P extends LambderMockRateLimitPolicies<S>> = {
+type LambderMockRateLimitsOptions<C, S, P extends LambderMockRateLimitPolicies<S>> = {
     policies: P & {
         [N in keyof P]: LambderMockSurplusKeys<P[N], LambderApiRateLimitPolicyConfig<LambderMockCallContext<S>>>;
+    } & {
+        [N in LambderContractRateLimitNames<C>]: LambderApiRateLimitPolicyConfig<LambderMockCallContext<S>>;
+    } & {
+        [N in keyof P & LambderContractRateLimitNames<C, "public">]: P[N] extends {
+            per: "session";
+        } ? {
+            per: never;
+        } : unknown;
+    } & {
+        [N in keyof P & LambderContractWindowOverrideNames<C>]: P[N] extends {
+            budget: "perPolicy";
+        } ? {
+            budget: never;
+        } : unknown;
     };
     /** Where attempts are counted. Default: a fresh LambderMemoryRateLimiter. */
     limiter?: LambderRateLimiter;
@@ -95,11 +128,45 @@ type LambderMockGuardsOption<C, S, G> = [
 } : {
     guards: G & LambderMockGuards<C, S> & LambderMockGuardShapes<S, G>;
 };
+/**
+ * The sessions, idempotency and rateLimits options: each required whenever
+ * the contract has an endpoint that needs it, for the guards option's reason.
+ * An entry that needs one the mock was created without cannot be registered,
+ * so leaving it out is an error here rather than a throw when the registry
+ * loads.
+ */
+type LambderMockSessionsOption<C, S> = [
+    LambderContractKeysWithMode<C, "session">
+] extends [never] ? {
+    /** Sessions over the memory store: `true` for the defaults, or the options. Off by default. */
+    sessions?: boolean | LambderMockSessionsOptions<S>;
+} : {
+    /** Sessions over the memory store: `true` for the defaults, or the options. Required: the contract has session endpoints. */
+    sessions: true | LambderMockSessionsOptions<S>;
+};
+type LambderMockIdempotencyOption<C, S, I> = [
+    LambderContractIdempotentKeys<C>
+] extends [never] ? {
+    /** Idempotency over a memory store: `true` for the defaults, or the options. Off by default. */
+    idempotency?: I & LambderMockSurplusKeys<I, LambderMockIdempotencyOptions<S>>;
+} : {
+    /** Idempotency over a memory store: `true` for the defaults, or the options. Required: the contract has idempotent endpoints. */
+    idempotency: I & ([I] extends [false] ? never : unknown) & LambderMockSurplusKeys<I, LambderMockIdempotencyOptions<S>>;
+};
+type LambderMockRateLimitsOption<C, S, P extends LambderMockRateLimitPolicies<S>> = [
+    LambderContractRateLimitNames<C>
+] extends [never] ? {
+    /** The rate-limit policies endpoints may restate, over a memory limiter unless one is given. Off by default. */
+    rateLimits?: LambderMockRateLimitsOptions<C, S, P>;
+} : {
+    /** The rate-limit policies endpoints may restate, over a memory limiter unless one is given. Required: the contract references policies. */
+    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> = {
     [N in keyof G]: LambderMockSurplusKeys<G[N], LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>>;
 };
-export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>> = LambderMockGuardsOption<C, S, G> & {
+export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicies<S> = LambderMockRateLimitPolicies<S>, I extends boolean | LambderMockIdempotencyOptions<S> = boolean | LambderMockIdempotencyOptions<S>> = LambderMockGuardsOption<C, S, G> & LambderMockSessionsOption<C, S> & LambderMockIdempotencyOption<C, S, I> & LambderMockRateLimitsOption<C, S, P> & {
     /** Stamped on every answer's envelope as apiVersion, as the server's option is. */
     apiVersion?: string;
     /** The version floor, as on the server: a call naming a lower `version` answers versionExpired whatever its signature says. */
@@ -108,12 +175,6 @@ export type LambderMockAppOptions<C, S, G, P extends LambderMockRateLimitPolicie
     apiSignatures?: LambderApiSignatureMap;
     /** Artificial latency per call; off by default. */
     latency?: LambderMockLatency;
-    /** Sessions over the memory store: `true` for the defaults, or the options. Off by default: session endpoints then fail at registration. */
-    sessions?: boolean | LambderMockSessionsOptions<S>;
-    /** The rate-limit policies endpoints may restate, over a memory limiter unless one is given. Off by default. */
-    rateLimits?: LambderMockRateLimitsOptions<S, P>;
-    /** Idempotency over a memory store: `true` for the defaults, or the options. Off by default. */
-    idempotency?: I & LambderMockSurplusKeys<I, LambderMockIdempotencyOptions<S>>;
     /**
      * The host the runtime's cookies belong to: what signIn plants them
      * under, what the direct transport's jar scopes them by, what the MSW

package/dist/mock/LambderMockTypes.d.ts

@@ -90,8 +90,10 @@ export type LambderMockContext<C, K extends keyof C, S, G> = Omit<LambderMockCal
  * The guard map a mock app must declare: one guard per name any endpoint of
  * the contract declares, and for every guard the contract knows in
  * guardInput mode, a `guardInput` schema whose output is what the server
- * inferred. A missing name or a schema that parses to something else fails
- * at the `guards` option.
+ * inferred. A guard a public endpoint names may not require a session, since
+ * an entry naming one cannot be registered. A missing name, a schema that
+ * parses to something else, or a session guard where the contract has a
+ * public endpoint fails at the `guards` option.
  */
 export type LambderMockGuards<C, S = any> = {
     [N in LambderContractGuardNames<C>]: LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;
@@ -99,6 +101,10 @@ export type LambderMockGuards<C, S = any> = {
     [N in LambderContractGuardInputNames<C>]: {
         guardInput: z.ZodType<LambderContractGuardInput<C, N>, any>;
     };
+} & {
+    [N in LambderContractGuardNames<C, "public">]: {
+        session?: false;
+    };
 };
 export type LambderMockHandler<C, K extends keyof C, S, G> = (ctx: LambderMockContext<C, K, S, G>) => LambderMockOutputOf<C, K> | Promise<LambderMockOutputOf<C, K>>;
 /**

package/dist/shared/wire/LambderApiContract.d.ts

@@ -85,6 +85,56 @@ export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInpu
 export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
     [K in Name]: Entry;
 };
+/**
+ * The contract as one object type, for the `export interface` a consuming
+ * app declares its contract through:
+ *
+ * ```ts
+ * export interface ApiContractType extends LambderFlattenContract<typeof lambder.ApiContract> {}
+ * ```
+ *
+ * Chaining leaves the contract an intersection one member deep per endpoint
+ * (LambderMergeContract above), and every `C[K]` written against a type
+ * parameter then resolves the property across all of them. That lookup is
+ * the atom the reading helpers below are built from, so its cost is paid
+ * again by each of them, per endpoint, in every app that registers a mock,
+ * declares a needs map, or otherwise reads the contract generically: in a
+ * 182-endpoint app one indexed access measured ~3,000 type instantiations
+ * and one mock registration ~18,000.
+ *
+ * Extending an interface is what collapses it. An interface's members are
+ * declared, so they are resolved once for the whole declaration rather than
+ * per lookup, and the same access measured ~6 instantiations after the
+ * change: a 182-endpoint app's frontend type check went from 27.8M
+ * instantiations to 7.0M and from 20.2s to 10.6s of check time. The alias
+ * form (`type C = LambderFlattenContract<...>`) does NOT do this: a mapped
+ * type stays deferred and each lookup pays the full cost again, so the
+ * `interface ... extends` spelling is the point.
+ *
+ * Diagnostics are the same ones, and they read better: a message naming the
+ * contract prints the interface by name, where the intersection is printed
+ * as a truncated spill of entries.
+ *
+ * Every endpoint name must be a string literal for an interface to extend
+ * the result, which registration through addApi/addSessionApi guarantees.
+ *
+ * Two things quietly undo it, both of which look like tidying:
+ *
+ * - `@typescript-eslint/no-empty-object-type` reports the empty body as
+ *   "equivalent to its supertype" and its fix is a type alias, which is the
+ *   one spelling that does not collapse anything. Disable the rule on the
+ *   line rather than taking the fix.
+ * - Extending anything but a mapped type loses the inferable index signature.
+ *   An interface has none of its own, so a hand-written `interface C { ... }`
+ *   is not assignable to LambderApiContractShape and is rejected by
+ *   initLambderMock<C>, LambderCaller<C> and LambderInvokeCaller<C>;
+ *   extending this mapped type is what keeps it. api-contract.test.ts pins
+ *   that, along with the flattened contract being the same type member for
+ *   member.
+ */
+export type LambderFlattenContract<C> = {
+    [K in keyof C]: C[K];
+};
 /** Guard names referenced by a guards option, whichever of its three forms is used. */
 export type LambderGuardNamesIn<TOpt> = TOpt extends string ? TOpt : TOpt extends readonly (infer N extends string)[] ? N : TOpt extends object ? keyof TOpt & string : never;
 /** The endpoint's mode; a contract written without one admits either. */
@@ -99,10 +149,10 @@ export type LambderContractKeysWithMode<C, M extends LambderApiMode> = {
 export type LambderContractGuardsOf<C, K extends keyof C> = C[K] extends {
     guards: infer G;
 } ? G : never;
-/** Every guard name any endpoint of the contract declares. */
-export type LambderContractGuardNames<C> = {
-    [K in keyof C]: LambderGuardNamesIn<LambderContractGuardsOf<C, K>>;
-}[keyof C] & string;
+/** Every guard name any endpoint of the contract declares, or only the endpoints of mode M. */
+export type LambderContractGuardNames<C, M extends LambderApiMode = LambderApiMode> = {
+    [K in LambderContractKeysWithMode<C, M>]: LambderGuardNamesIn<LambderContractGuardsOf<C, K>>;
+}[LambderContractKeysWithMode<C, M>] & string;
 /** The endpoint's guardInputs requirement, or never when its guards take no client input. */
 export type LambderContractGuardInputsOf<C, K extends keyof C> = C[K] extends {
     guardInputs: infer G;
@@ -123,6 +173,10 @@ export type LambderContractGuardInputNames<C> = {
 export type LambderContractRateLimitOf<C, K extends keyof C> = C[K] extends {
     rateLimit: infer R;
 } ? R : never;
+/** Every rate-limit policy name any endpoint of the contract references, or only the endpoints of mode M. The rateLimit option takes the guards option's three forms, so the names come out the same way. */
+export type LambderContractRateLimitNames<C, M extends LambderApiMode = LambderApiMode> = {
+    [K in LambderContractKeysWithMode<C, M>]: LambderGuardNamesIn<LambderContractRateLimitOf<C, K>>;
+}[LambderContractKeysWithMode<C, M>] & string;
 /** The endpoint's idempotency option as written, or never. */
 export type LambderContractIdempotencyOf<C, K extends keyof C> = C[K] extends {
     idempotency: infer I;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "7.2.3",
+  "version": "7.2.5",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [